Merge pull request #114 from gbrlcustodio/fix/smoke-findings

fix: smoke QA hardening (phase fields, invites, AI preflight)

Author: adriannoes

CHANGELOG.md

@@ -37,5 +37,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 - **CLI**: `pipefy agent update` resolves slug-style `fieldId` values in behaviors for error-path enrichment the same way as the happy path (via `PipefyClient.update_ai_agent`), so `RECORD_NOT_SAVED` diagnostics do not falsely blame slug tokens as unknown pipe fields.
 - **CLI / MCP**: `field-condition create` / `update` accept legacy `actionId: "hidden"` on condition actions; the SDK normalizes to `hide` before mutations.
+- **SDK**: `PipeConfigService.update_phase_field` accepts optional `phase_id` / `pipe_id` and resolves a slug-like `field_id` to the field's `uuid` (injected as `input.uuid` while the slug stays as `input.id`, matching Pipefy's `UpdatePhaseFieldInput` contract). The pipe-wide lookup runs phase fetches concurrently via `asyncio.gather`; partial phase-fetch failures raise an actionable `ValueError` instead of returning an ambiguous match. Surfaced through MCP `update_phase_field(phase_id=…, pipe_id=…)` and CLI `pipefy field update --extra '{"phase_id":"…"}'`.
+- **MCP**: `delete_phase_field` preview now enumerates `dependents.field_conditions` even when the rule only references the field in expression `field_address` (not just `actions[].phaseFieldId`); the condition tree walker has a defensive depth cap of 16.
+- **SDK / MCP**: `PipefyClient.get_automation_logs_by_repo` short-circuits to an empty page when the pipe has no automations (was returning `MULTIPLE_INVALID_INPUT: Automation_ids can't be blank` from the API).
+- **SDK / MCP**: `invite_members` validates each row with a new `MemberInvite` Pydantic model (`EmailStr` + non-blank `role_name`, lowercase normalization, `extra="forbid"`) and raises a single-line `ValueError` pointing at the offending field. MCP surfaces it as `INVALID_ARGUMENTS`.
+- **SDK**: `ai_preflight.validate_ai_automation_prompt_sdk` flags overlap when the same `%{internal_id}` appears both in the prompt and in `field_ids`, in English, citing the API rejection message.
+- **MCP**: `find_records` returns the unified envelope `pagination={has_more, end_cursor, page_size}` (snake_case) when the unified envelope flag is on, matching `get_table_records`.
+- **MCP / CLI docs**: `create_card`, `create_table_record`, `clone_pipe`, and `create_field_condition` docstrings clarify title-derivation quirks, async clone phases, and the `phaseFieldId` discovery path.
+- **SDK**: `MemberInvite` lives at `pipefy_sdk.MemberInvite` (re-exported in the top-level `__all__`); `slug_like_field_token` / `looks_like_uuid_token` extracted to `pipefy_sdk.utils.field_tokens` for reuse across services.
 
 ### Removed

docs/mcp/tools/database-tables.md

@@ -6,7 +6,7 @@ Tables, records (rows), and schema columns (table fields) for org Database Table
 
 - Same conventions as pipe building: `introspect_type` on inputs such as `CreateTableFieldInput` / `UpdateTableFieldInput`, `debug=true` on mutations, `extra_input` where the tool exposes it.
 - **IDs:** `table_id`, record IDs, and related parameters are **strings** in GraphQL (numeric strings for many org tables, or opaque tokens such as `fIVcd19N`). Prefer quoted strings in MCP/JSON; unquoted numeric JSON may be coerced where the tool uses the shared ID type. See [Pipes & cards — Pipefy IDs](pipes-and-cards.md#pipefy-ids-type-safety).
-- **Pagination:** `get_table_records` and `find_records` support `first` / `after`. Read `pageInfo.hasNextPage` and `pageInfo.endCursor` from the response and pass `after=endCursor` for the next page (default page size for listing records is 50; caps apply — see tool docstrings).
+- **Pagination:** `get_table_records` and `find_records` support `first` / `after`. With the unified MCP envelope, read top-level `pagination.has_more` and `pagination.end_cursor` (and `pagination.page_size`) and pass `after=end_cursor` for the next page (default page size for listing records is 50; caps apply — see tool docstrings).
 
 ---
 

docs/parity.md

@@ -64,7 +64,7 @@ This matrix is the source of truth for **MCP tool ↔ `pipefy` CLI** coverage. I
 | `export_pipe_report` | `pipefy report-pipe export` | shipped | Exports + reports. |
 | `fill_card_phase_fields` | — | deferred | Card bulk fill; not in FR-5.2 launch command list (may follow **5.2**). |
 | `find_cards` | `pipefy card find` | shipped | Task **5.2** (`--pipe`, `--field`, `--value`). |
-| `find_records` | `pipefy record find` | shipped | Task **5.7** (`--filter` JSON with `field_id` + `field_value`). |
+| `find_records` | `pipefy record find` | shipped | Task **5.7** (`--filter` JSON with `field_id` + `field_value`). Unified MCP envelope: top-level `pagination` uses `has_more` / `end_cursor` / `page_size` (same as `get_table_records`). |
 | `get_agents_usage` | `pipefy usage agents` | shipped | Task **10.3** (`--organization`, `--from`, `--to`, optional `--filters` / `--search` / `--sort` JSON). |
 | `get_ai_agent` | `pipefy agent get` | shipped | AI Agents domain. |
 | `get_ai_agent_log_details` | `pipefy agent logs get` | shipped | AI Agents domain. |
@@ -135,7 +135,7 @@ This matrix is the source of truth for **MCP tool ↔ `pipefy` CLI** coverage. I
 | `update_label` | `pipefy label update` | shipped | Task **5.8**. |
 | `update_organization_report` | `pipefy report-org update` | shipped | Organization reports. |
 | `update_phase` | `pipefy phase update` | shipped | Task **5.4**. |
-| `update_phase_field` | `pipefy field update` | shipped | Task **5.5** (``--extra`` JSON). |
+| `update_phase_field` | `pipefy field update` | shipped | Task **5.5** (``--extra`` JSON). Optional ``phase_id`` / ``pipe_id`` in ``--extra`` resolve slug ``field_id`` to ``internal_id`` when ``uuid`` is omitted. |
 | `update_pipe` | `pipefy pipe update` | shipped | Task **5.3** (`--name`, `--icon`, `--color`, `--preferences` JSON). |
 | `update_pipe_relation` | `pipefy relation pipe update` | shipped | Task **5.10**. |
 | `update_pipe_report` | `pipefy report-pipe update` | shipped | Reports domain. |

packages/cli/src/pipefy_cli/skills/pipefy-database-tables.md

@@ -18,7 +18,7 @@ Tables, records (rows), schema columns (table fields), and attachments for Pipef
 ## Cross-cutting patterns
 
 - Same conventions as pipe building: `introspect_type` on inputs such as `CreateTableFieldInput` / `UpdateTableFieldInput`, `debug=true` on mutations.
-- **Pagination:** `get_table_records` and `find_records` support `first` / `after`. Read `pageInfo.hasNextPage` and `pageInfo.endCursor` from the response and pass `after=endCursor` for the next page (default page size is 50).
+- **Pagination:** `get_table_records` and `find_records` support `first` / `after`. With the unified MCP envelope, read top-level `pagination.has_more` and `pagination.end_cursor` (and `pagination.page_size`) and pass `after=end_cursor` for the next page (default page size is 50).
 - **Destructive deletes** (`delete_table`, `delete_table_record`, `delete_table_field`) use a **mandatory two-step flow**: call without `confirm=true` first (preview), then with `confirm=true` after user approves.
 
 ---

packages/cli/tests/test_cli_tasks_10_11.py

@@ -73,7 +73,14 @@ def test_ai_automation_validate_prompt_json(
     mock_client.get_pipe_with_preferences = AsyncMock(
         return_value={
             "pipe": {
-                "phases": [{"fields": [{"internal_id": "9", "id": "f", "label": "L"}]}],
+                "phases": [
+                    {
+                        "fields": [
+                            {"internal_id": "9", "id": "f", "label": "L"},
+                            {"internal_id": "42", "id": "o", "label": "Out"},
+                        ]
+                    }
+                ],
                 "start_form_fields": [],
                 "preferences": {"aiAgentsEnabled": True},
                 "organizationId": "300",
@@ -98,7 +105,7 @@ def test_ai_automation_validate_prompt_json(
                 "--prompt",
                 "Hello %{9}",
                 "--field-ids",
-                '["9"]',
+                '["42"]',
                 "--event-id",
                 "card_created",
                 "--json",
@@ -521,15 +528,21 @@ def test_ai_automation_update_auto_fetches_prompt_when_omitted(
 ):
     """When ``--prompt``/``--field-ids`` are omitted, the CLI re-uses current values for pre-flight only."""
     oauth_env("ai-up-auto")
-    existing = _ai_automation_row("Summarize: %{9}", ["9"])
+    # Prompt references field 9 as input; output field 88 is distinct so overlap preflight passes.
+    existing = _ai_automation_row("Summarize: %{9}", ["88"])
     mock_client = MagicMock()
     mock_client.ai_automation_available = True
     mock_client.get_automation = AsyncMock(return_value=existing)
     mock_client.get_pipe_with_preferences = AsyncMock(
         return_value={
             "pipe": {
                 "phases": [
-                    {"fields": [{"internal_id": "9", "id": "f9", "label": "L"}]}
+                    {
+                        "fields": [
+                            {"internal_id": "9", "id": "f9", "label": "L"},
+                            {"internal_id": "88", "id": "f88", "label": "Out"},
+                        ]
+                    }
                 ],
                 "start_form_fields": [],
                 "preferences": {"aiAgentsEnabled": True},

packages/cli/tests/test_phase_field_commands.py

@@ -118,6 +118,41 @@ def test_field_create_json(runner, clean_pipefy_env, saved_cwd, oauth_env):
     )
 
 
+def test_field_update_forwards_extra_phase_id_for_slug_resolution(
+    runner, clean_pipefy_env, saved_cwd, oauth_env
+):
+    """``--extra '{"phase_id": ...}'`` reaches ``client.update_phase_field`` verbatim.
+
+    Locks the CLI side of the smoke-2026-05-15 slug-resolution fix: the SDK can only
+    map ``"priority"`` to its ``internal_id`` if the CLI forwards ``phase_id`` as a
+    keyword argument.
+    """
+    oauth_env("fld-upd")
+    mock_client = MagicMock()
+    mock_client.update_phase_field = AsyncMock(
+        return_value={"updatePhaseField": {"phase_field": {"id": "429358624"}}}
+    )
+    with patch(
+        "pipefy_cli.commands._common.get_authenticated_client",
+        return_value=mock_client,
+    ):
+        result = runner.invoke(
+            app,
+            [
+                "field",
+                "update",
+                "priority",
+                "--extra",
+                '{"label": "Priority", "phase_id": "343162749"}',
+                "--json",
+            ],
+        )
+    assert result.exit_code == 0, result.stdout
+    mock_client.update_phase_field.assert_awaited_once_with(
+        "priority", label="Priority", phase_id="343162749"
+    )
+
+
 def test_field_delete_yes(runner, clean_pipefy_env, saved_cwd, oauth_env):
     oauth_env("fld-del")
     mock_client = MagicMock()

packages/mcp/src/pipefy_mcp/tools/field_condition_tools.py

@@ -212,10 +212,11 @@ async def create_field_condition(
                     objects with ``structure_id``, ``field_address``, ``operation``, ``value``) and
                     ``expressions_structure`` (array of arrays of string indices).
                     Discover via: ``get_phase_fields(phase_id)[].internal_id`` for ``field_address``.
-                actions: List of ``FieldConditionActionInput`` dicts; use ``phaseFieldId`` (often the
-                    field's ``internal_id`` from ``get_phase_fields``). Each action must include
-                    ``actionId`` (``hide`` or ``show``); legacy ``hidden`` is mapped to ``hide``.
-                    Discover via: ``get_phase_fields(phase_id)[].internal_id`` for ``phaseFieldId``.
+                actions: List of ``FieldConditionActionInput`` dicts; each needs ``phaseFieldId``.
+                    ``phaseFieldId`` is usually the field's ``internal_id`` from ``get_phase_fields``,
+                    same pattern as ``fill_card_phase_fields`` and ``create_card_relation``.
+                    Each action must include ``actionId`` (``hide`` or ``show``); legacy ``hidden`` is
+                    mapped to ``hide``.
                 name: Rule display name. Required by the API; may also be provided via
                     ``extra_input={"name": ...}`` for back-compat.
                 extra_input: Optional extra keys for ``createFieldConditionInput`` (e.g. ``index``).

packages/mcp/src/pipefy_mcp/tools/member_tool_helpers.py

@@ -45,13 +45,16 @@ def build_member_success_payload(
     return cast(MemberMutationSuccessPayload, payload)
 
 
-def build_member_error_payload(*, message: str) -> dict[str, Any]:
+def build_member_error_payload(
+    *, message: str, code: str | None = None
+) -> dict[str, Any]:
     """``success: False`` with ``error`` text.
 
     Args:
         message: User-visible failure reason.
+        code: Optional machine-readable error code (e.g. ``INVALID_ARGUMENTS``).
     """
-    return tool_error(message)
+    return tool_error(message, code=code)
 
 
 def handle_member_tool_graphql_error(

packages/mcp/src/pipefy_mcp/tools/member_tools.py

@@ -64,6 +64,11 @@ async def invite_members(
                     )
             try:
                 raw = await client.invite_members(pipe_id, members)
+            except ValueError as exc:
+                return build_member_error_payload(
+                    message=str(exc),
+                    code="INVALID_ARGUMENTS",
+                )
             except Exception as exc:  # noqa: BLE001
                 return handle_member_tool_graphql_error(
                     exc,

packages/mcp/src/pipefy_mcp/tools/pipe_config_tool_helpers.py

@@ -282,6 +282,32 @@ def field_condition_actions_error_message(
     return None
 
 
+_MAX_CONDITION_TREE_DEPTH = 16
+
+
+def _condition_tree_references_targets(
+    obj: Any, targets: set[str], depth: int = 0
+) -> bool:
+    """Return True if any node in the condition subtree references one of the targets."""
+    if not targets:
+        return False
+    if depth > _MAX_CONDITION_TREE_DEPTH:
+        return False
+    if isinstance(obj, dict):
+        for key, val in obj.items():
+            if key in ("field_address", "phaseFieldId") and val is not None:
+                if str(val).strip() in targets:
+                    return True
+            if _condition_tree_references_targets(val, targets, depth + 1):
+                return True
+        return False
+    if isinstance(obj, list):
+        return any(
+            _condition_tree_references_targets(item, targets, depth + 1) for item in obj
+        )
+    return False
+
+
 async def find_phase_field_dependents(
     client: PipefyClient,
     *,
@@ -290,7 +316,7 @@ async def find_phase_field_dependents(
     field_uuid: str | None,
     field_slug: str | None,
 ) -> list[dict[str, Any]]:
-    """Return field conditions on ``phase_id`` whose actions reference the field."""
+    """Return field conditions on ``phase_id`` that reference the field in actions or conditions."""
     try:
         payload = await client.get_field_conditions(phase_id)
     except Exception:  # noqa: BLE001
@@ -303,19 +329,26 @@ async def find_phase_field_dependents(
         if not isinstance(cond, dict):
             continue
         actions = cond.get("actions") or []
+        matched = False
         for action in actions:
             if not isinstance(action, dict):
                 continue
             raw_pf = action.get("phaseFieldId")
             if raw_pf is not None and str(raw_pf) in targets:
-                out.append(
-                    {
-                        "id": cond.get("id"),
-                        "name": cond.get("name"),
-                        "action_count": len(actions),
-                    }
-                )
+                matched = True
                 break
+        if not matched and _condition_tree_references_targets(
+            cond.get("condition"), targets
+        ):
+            matched = True
+        if matched:
+            out.append(
+                {
+                    "id": cond.get("id"),
+                    "name": cond.get("name"),
+                    "action_count": len(actions) if isinstance(actions, list) else 0,
+                }
+            )
     return out