@josephyan/qingflow-app-builder-mcp 0.2.0-beta.39 → 0.2.0-beta.40

package/src/qingflow_mcp/builder_facade/service.py

@@ -29,9 +29,11 @@ from ..tools.solution_tools import SolutionTools
 from ..tools.view_tools import ViewTools
 from ..tools.workflow_tools import WorkflowTools
 from .models import (
+    AppChartsReadResponse,
     AppFieldsReadResponse,
     AppFlowReadResponse,
     AppLayoutReadResponse,
+    PortalReadSummaryResponse,
     AppReadSummaryResponse,
     AppViewsReadResponse,
     ChartApplyRequest,
@@ -1048,7 +1050,13 @@ class AiBuilderFacade:
             "request_id": None,
             "suggested_next_call": None,
             "noop": False,
-            "verification": {"app_exists": True},
+            "warnings": _warnings_from_verification_hints(verification_hints),
+            "verification": {
+                "app_exists": True,
+                "views_read_unavailable": views_unavailable,
+                "workflow_read_unavailable": workflow_unavailable,
+            },
+            "verified": not views_unavailable and not workflow_unavailable,
             **response.model_dump(mode="json"),
         }
 
@@ -1092,7 +1100,9 @@ class AiBuilderFacade:
             "request_id": None,
             "suggested_next_call": None,
             "noop": False,
+            "warnings": [],
             "verification": {"app_exists": True},
+            "verified": True,
             **response.model_dump(mode="json"),
         }
 
@@ -1128,7 +1138,9 @@ class AiBuilderFacade:
             "request_id": None,
             "suggested_next_call": None,
             "noop": False,
+            "warnings": _layout_read_warnings(response.unplaced_fields),
             "verification": {"app_exists": True},
+            "verified": True,
             **response.model_dump(mode="json"),
         }
 
@@ -1160,7 +1172,9 @@ class AiBuilderFacade:
             "request_id": None,
             "suggested_next_call": None,
             "noop": False,
+            "warnings": [],
             "verification": {"app_exists": True},
+            "verified": True,
             **response.model_dump(mode="json"),
         }
 
@@ -1194,7 +1208,99 @@ class AiBuilderFacade:
             "request_id": None,
             "suggested_next_call": None,
             "noop": False,
+            "warnings": [_warning("WORKFLOW_READ_UNAVAILABLE", "workflow summary readback is unavailable")] if workflow_unavailable else [],
             "verification": {"app_exists": True, "workflow_read_unavailable": workflow_unavailable},
+            "verified": not workflow_unavailable,
+            **response.model_dump(mode="json"),
+        }
+
+    def app_read_charts_summary(self, *, profile: str, app_key: str) -> JSONObject:
+        try:
+            app_result = self.app_resolve(profile=profile, app_key=app_key)
+            if app_result.get("status") != "success":
+                return app_result
+            resolved_app_key = str(app_result.get("app_key") or app_key)
+            items = self.charts.qingbi_report_list(profile=profile, app_key=resolved_app_key).get("items") or []
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _failed_from_api_error(
+                "CHARTS_READ_FAILED",
+                api_error,
+                normalized_args={"app_key": app_key},
+                details={"app_key": app_key},
+                suggested_next_call={"tool_name": "app_read_summary", "arguments": {"profile": profile, "app_key": app_key}},
+            )
+        charts = _summarize_charts(items)
+        response = AppChartsReadResponse(
+            app_key=resolved_app_key,
+            charts=charts,
+            chart_count=len(charts),
+        )
+        return {
+            "status": "success",
+            "error_code": None,
+            "recoverable": False,
+            "message": "read app charts summary",
+            "normalized_args": {"app_key": resolved_app_key},
+            "missing_fields": [],
+            "allowed_values": {},
+            "details": {},
+            "request_id": None,
+            "suggested_next_call": None,
+            "noop": False,
+            "warnings": [],
+            "verification": {"app_exists": True},
+            "verified": True,
+            **response.model_dump(mode="json"),
+        }
+
+    def portal_read_summary(self, *, profile: str, dash_key: str, being_draft: bool = True) -> JSONObject:
+        try:
+            result = self.portals.portal_get(profile=profile, dash_key=dash_key, being_draft=being_draft).get("result") or {}
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _failed_from_api_error(
+                "PORTAL_READ_FAILED",
+                api_error,
+                normalized_args={"dash_key": dash_key, "being_draft": being_draft},
+                details={"dash_key": dash_key, "being_draft": being_draft},
+                suggested_next_call={"tool_name": "portal_read_summary", "arguments": {"profile": profile, "dash_key": dash_key, "being_draft": being_draft}},
+            )
+        response = PortalReadSummaryResponse(
+            dash_key=dash_key,
+            being_draft=being_draft,
+            dash_name=str(result.get("dashName") or "").strip() or None,
+            package_tag_ids=[
+                tag_id
+                for tag_id in (
+                    _coerce_positive_int((item or {}).get("tagId"))
+                    for item in (result.get("tags") or [])
+                    if isinstance(item, dict)
+                )
+                if tag_id is not None
+            ],
+            dash_icon=str(result.get("dashIcon") or "").strip() or None,
+            hide_copyright=bool(result.get("hideCopyright")) if "hideCopyright" in result else None,
+            config_keys=sorted(str(key) for key in (result.get("config") or {}).keys()) if isinstance(result.get("config"), dict) else [],
+            dash_global_config_keys=sorted(str(key) for key in (result.get("dashGlobalConfig") or {}).keys()) if isinstance(result.get("dashGlobalConfig"), dict) else [],
+            section_count=len(result.get("components") or []) if isinstance(result.get("components"), list) else 0,
+            sections=_summarize_portal_sections(result.get("components")),
+        )
+        return {
+            "status": "success",
+            "error_code": None,
+            "recoverable": False,
+            "message": "read portal summary",
+            "normalized_args": {"dash_key": dash_key, "being_draft": being_draft},
+            "missing_fields": [],
+            "allowed_values": {},
+            "details": {},
+            "request_id": None,
+            "suggested_next_call": None,
+            "noop": False,
+            "warnings": [],
+            "verification": {"portal_exists": True, "being_draft": being_draft},
+            "verified": True,
             **response.model_dump(mode="json"),
         }
 
@@ -2843,6 +2949,7 @@ class AiBuilderFacade:
                 "request_id": None,
                 "suggested_next_call": None,
                 "noop": True,
+                "warnings": [],
                 "verification": {"published": True, "package_attached": package_already_attached, "views_ok": True},
                 "app_key": app_key,
                 "published": True,
@@ -2892,6 +2999,11 @@ class AiBuilderFacade:
         views = views or []
         views_ok = isinstance(views, list) and not views_unavailable
         verified = bool(base.get("appPublishStatus") in {1, 2}) and (package_attached is not False) and views_ok
+        warnings = _publish_verify_warnings(
+            package_attached=package_attached,
+            views_unavailable=views_unavailable,
+            verified=verified,
+        )
         return {
             "status": "success" if verified else "partial_success",
             "error_code": None if not views_unavailable else "VIEWS_READBACK_PENDING",
@@ -2909,6 +3021,7 @@ class AiBuilderFacade:
                 "arguments": {"profile": profile, "tag_id": expected_package_tag_id, "app_key": app_key},
             },
             "noop": False,
+            "warnings": warnings,
             "verification": {"published": bool(base.get("appPublishStatus") in {1, 2}), "package_attached": package_attached, "views_ok": views_ok, "views_read_unavailable": views_unavailable},
             "app_key": app_key,
             "published": bool(base.get("appPublishStatus") in {1, 2}),
@@ -2937,7 +3050,7 @@ class AiBuilderFacade:
                 api_error,
                 normalized_args=normalized_args,
                 details={"app_key": app_key},
-                suggested_next_call={"tool_name": "chart_apply", "arguments": {"profile": profile, **normalized_args}},
+                suggested_next_call={"tool_name": "app_charts_apply", "arguments": {"profile": profile, **normalized_args}},
             )
 
         field_lookup = _build_public_field_lookup(fields)
@@ -2951,11 +3064,14 @@ class AiBuilderFacade:
             for item in existing_chart_items
             if isinstance(item, dict) and _extract_chart_identifier(item)
         }
-        existing_by_name = {
-            str(item.get("chartName") or "").strip(): deepcopy(item)
-            for item in existing_chart_items
-            if isinstance(item, dict) and str(item.get("chartName") or "").strip()
-        }
+        existing_by_name: dict[str, list[dict[str, Any]]] = {}
+        for item in existing_chart_items:
+            if not isinstance(item, dict):
+                continue
+            item_name = str(item.get("chartName") or "").strip()
+            if not item_name:
+                continue
+            existing_by_name.setdefault(item_name, []).append(deepcopy(item))
 
         chart_results: list[dict[str, Any]] = []
         created_ids: list[str] = []
@@ -2968,15 +3084,24 @@ class AiBuilderFacade:
                 existing = None
                 if patch.chart_id:
                     existing = existing_by_id.get(str(patch.chart_id))
+                    if existing is None:
+                        raise ValueError(f"chart_id '{patch.chart_id}' was not found under app '{app_key}'")
                 if existing is None:
-                    existing = existing_by_name.get(patch.name)
-                chart_id = _extract_chart_identifier(existing or {}) or str(patch.chart_id or f"mcp_{uuid4().hex[:16]}")
+                    name_matches = list(existing_by_name.get(patch.name) or [])
+                    if len(name_matches) > 1:
+                        raise ValueError(
+                            f"chart name '{patch.name}' is ambiguous under app '{app_key}'; supply chart_id to target an exact chart"
+                        )
+                    if name_matches:
+                        existing = deepcopy(name_matches[0])
+                chart_id = _extract_chart_identifier(existing or {}) or str(patch.chart_id or "")
                 existing_name = str((existing or {}).get("chartName") or "").strip()
                 existing_type = _normalize_backend_chart_type((existing or {}).get("chartType"))
                 target_type = _map_public_chart_type_to_backend(patch.chart_type)
                 if existing is None:
+                    temp_chart_id = str(patch.chart_id or f"mcp_{uuid4().hex[:16]}")
                     create_payload = {
-                        "chartId": chart_id,
+                        "chartId": temp_chart_id,
                         "chartName": patch.name,
                         "chartType": target_type,
                         "dataSourceType": "qingflow",
@@ -2992,15 +3117,30 @@ class AiBuilderFacade:
                     created_chart_id = _extract_chart_identifier(create_result or {})
                     if not created_chart_id:
                         refreshed_items = self.charts.qingbi_report_list(profile=profile, app_key=app_key).get("items") or []
-                        refreshed_existing = _find_chart_by_name(
+                        refreshed_matches = _find_charts_by_name(
                             refreshed_items,
                             chart_name=patch.name,
                             chart_type=target_type,
                         )
-                        created_chart_id = _extract_chart_identifier(refreshed_existing or {})
-                    if created_chart_id:
-                        chart_id = created_chart_id
+                        if len(refreshed_matches) == 1:
+                            created_chart_id = _extract_chart_identifier(refreshed_matches[0])
+                        elif len(refreshed_matches) > 1:
+                            raise ValueError(
+                                f"created chart '{patch.name}' could not be uniquely resolved from readback; supply chart_id on the next update"
+                            )
+                    if not created_chart_id:
+                        raise ValueError(
+                            f"created chart '{patch.name}' did not return a real chart_id and could not be confirmed from readback"
+                        )
+                    chart_id = created_chart_id
                     created_ids.append(chart_id)
+                    created_chart = {
+                        "chartId": chart_id,
+                        "chartName": patch.name,
+                        "chartType": target_type,
+                    }
+                    existing_by_id[chart_id] = deepcopy(created_chart)
+                    existing_by_name.setdefault(patch.name, []).append(deepcopy(created_chart))
                 elif existing_name != patch.name or existing_type != target_type:
                     self.charts.qingbi_report_update_base(
                         profile=profile,
@@ -3008,6 +3148,19 @@ class AiBuilderFacade:
                         payload={"chartName": patch.name, "chartType": target_type},
                     )
                     updated_ids.append(chart_id)
+                    updated_chart = deepcopy(existing or {})
+                    updated_chart["chartId"] = chart_id
+                    updated_chart["chartName"] = patch.name
+                    updated_chart["chartType"] = target_type
+                    existing_by_id[chart_id] = deepcopy(updated_chart)
+                    old_name = existing_name
+                    if old_name and old_name in existing_by_name:
+                        existing_by_name[old_name] = [
+                            item for item in existing_by_name[old_name] if _extract_chart_identifier(item) != chart_id
+                        ]
+                        if not existing_by_name[old_name]:
+                            existing_by_name.pop(old_name, None)
+                    existing_by_name.setdefault(patch.name, []).append(deepcopy(updated_chart))
 
                 config_payload = _build_public_chart_config_payload(
                     patch=patch,
@@ -3127,37 +3280,54 @@ class AiBuilderFacade:
                 "allowed_values": {"chart.chart_type": [member.value for member in PublicChartType], "chart.filter.operator": [member.value for member in ViewFilterOperator]},
                 "details": {"per_chart_results": chart_results},
                 "request_id": failed_items[0].get("request_id"),
-                "suggested_next_call": {"tool_name": "chart_apply", "arguments": {"profile": profile, **normalized_args}},
+                "suggested_next_call": {"tool_name": "app_charts_apply", "arguments": {"profile": profile, **normalized_args}},
                 "backend_code": failed_items[0].get("backend_code"),
                 "http_status": failed_items[0].get("http_status"),
                 "noop": noop,
+                "warnings": _chart_apply_warnings(
+                    failed_items=failed_items,
+                    readback_unavailable=readback_unavailable,
+                    verified=False if failed_items else verified,
+                ),
                 "verification": {"charts_verified": False if failed_items else verified, "readback_unavailable": readback_unavailable},
                 "app_key": app_key,
                 "chart_results": chart_results,
                 "verified": False if failed_items else verified,
             }
+        result_verified = verified or noop
         return {
-            "status": "success" if verified or noop else "partial_success",
-            "error_code": None if verified or noop else "CHART_READBACK_PENDING",
-            "recoverable": not (verified or noop),
-            "message": "applied chart operations" if verified or noop else "applied chart operations; readback pending",
+            "status": "success" if result_verified else "partial_success",
+            "error_code": None if result_verified else "CHART_READBACK_PENDING",
+            "recoverable": not result_verified,
+            "message": "no chart changes requested" if noop else ("applied chart operations" if verified else "applied chart operations; readback pending"),
             "normalized_args": normalized_args,
             "missing_fields": [],
             "allowed_values": {"chart.chart_type": [member.value for member in PublicChartType], "chart.filter.operator": [member.value for member in ViewFilterOperator]},
             "details": {},
             "request_id": None,
-            "suggested_next_call": None if verified or noop else {"tool_name": "chart_apply", "arguments": {"profile": profile, **normalized_args}},
+            "suggested_next_call": None if result_verified else {"tool_name": "app_charts_apply", "arguments": {"profile": profile, **normalized_args}},
             "noop": noop,
-            "verification": {"charts_verified": verified, "readback_unavailable": readback_unavailable},
+            "warnings": _chart_apply_warnings(
+                failed_items=[],
+                readback_unavailable=False if noop else readback_unavailable,
+                verified=result_verified,
+            ),
+            "verification": {"charts_verified": result_verified, "readback_unavailable": False if noop else readback_unavailable},
             "app_key": app_key,
             "chart_results": chart_results,
-            "verified": verified or noop,
+            "verified": result_verified,
         }
 
     def portal_apply(self, *, profile: str, request: PortalApplyRequest) -> JSONObject:
         normalized_args = request.model_dump(mode="json")
         dash_key = str(request.dash_key or "").strip()
         creating = not dash_key
+        verify_dash_name = creating or request.dash_name is not None
+        verify_dash_icon = bool(request.icon or request.color)
+        verify_auth = request.auth is not None
+        verify_hide_copyright = request.hide_copyright is not None
+        verify_dash_global_config = request.dash_global_config is not None
+        verify_tags = creating or request.package_tag_id is not None
         try:
             base_payload = self.portals.portal_get(profile=profile, dash_key=dash_key, being_draft=True).get("result") if dash_key else {}
         except (QingflowApiError, RuntimeError) as error:
@@ -3258,16 +3428,59 @@ class AiBuilderFacade:
         draft_components = draft_result.get("components") if isinstance(draft_result, dict) else None
         expected_count = len(request.sections)
         draft_verified = isinstance(draft_components, list) and len(draft_components) == expected_count
-        live_verified = not request.publish or (
-            isinstance(live_result, dict)
-            and isinstance(live_result.get("components"), list)
-            and len(live_result.get("components")) == expected_count
+        draft_meta_verified, draft_meta_mismatches = _verify_portal_readback(
+            actual=draft_result,
+            expected_payload=update_payload,
+            expected_section_count=expected_count,
+            requested_config_keys=set((request.config or {}).keys()),
+            verify_dash_name=verify_dash_name,
+            verify_dash_icon=verify_dash_icon,
+            verify_auth=verify_auth,
+            verify_hide_copyright=verify_hide_copyright,
+            verify_dash_global_config=verify_dash_global_config,
+            verify_tags=verify_tags,
+        )
+        live_verified: bool | None = None
+        live_meta_verified: bool | None = None
+        live_meta_mismatches: list[str] = []
+        if request.publish:
+            live_verified = (
+                isinstance(live_result, dict)
+                and isinstance(live_result.get("components"), list)
+                and len(live_result.get("components")) == expected_count
+            )
+            live_meta_verified, live_meta_mismatches = _verify_portal_readback(
+                actual=live_result,
+                expected_payload=update_payload,
+                expected_section_count=expected_count,
+                requested_config_keys=set((request.config or {}).keys()),
+                verify_dash_name=verify_dash_name,
+                verify_dash_icon=verify_dash_icon,
+                verify_auth=verify_auth,
+                verify_hide_copyright=verify_hide_copyright,
+                verify_dash_global_config=verify_dash_global_config,
+                verify_tags=verify_tags,
+            )
+        verified = (
+            draft_verified
+            and draft_meta_verified
+            and (published if request.publish else True)
+            and (live_verified if request.publish else True)
+            and (live_meta_verified if request.publish else True)
+            and not publish_failed
         )
-        verified = draft_verified and live_verified and (published if request.publish else True) and not publish_failed
         status = "success" if verified else "partial_success"
         error_code = None if verified else "PORTAL_READBACK_PENDING"
         if publish_failed:
             error_code = "PORTAL_PUBLISH_FAILED"
+        warnings = _portal_apply_warnings(
+            publish_failed=publish_failed,
+            draft_verified=draft_verified,
+            draft_meta_verified=draft_meta_verified,
+            live_verified=live_verified,
+            live_meta_verified=live_meta_verified,
+            publish_requested=request.publish,
+        )
         return {
             "status": status,
             "error_code": error_code,
@@ -3276,13 +3489,21 @@ class AiBuilderFacade:
             "normalized_args": normalized_args,
             "missing_fields": [],
             "allowed_values": {"section.source_type": ["chart", "view", "grid", "filter", "text", "link"]},
-            "details": {},
+            "details": {
+                "verification_mismatches": {
+                    "draft": draft_meta_mismatches,
+                    "live": live_meta_mismatches,
+                }
+            },
             "request_id": None,
             "suggested_next_call": None if verified else {"tool_name": "portal_apply", "arguments": {"profile": profile, **normalized_args}},
             "noop": False,
+            "warnings": warnings,
             "verification": {
                 "draft_verified": draft_verified,
+                "draft_metadata_verified": draft_meta_verified,
                 "live_verified": live_verified,
+                "live_metadata_verified": live_meta_verified,
                 "published": published,
                 "publish_failed": publish_failed,
             },
@@ -3321,9 +3542,11 @@ class AiBuilderFacade:
             "request_id": None,
             "suggested_next_call": None,
             "noop": False,
+            "warnings": [],
             "verification": {"published": True},
             "app_key": app_key,
             "published": True,
+            "verified": True,
         }
 
     def _resolve_form_edit_version(self, *, profile: str, app_key: str, current_schema: dict[str, Any]) -> int:
@@ -3338,6 +3561,10 @@ class AiBuilderFacade:
         if not isinstance(verification, dict):
             verification = {}
             response["verification"] = verification
+        warnings = response.get("warnings")
+        if not isinstance(warnings, list):
+            warnings = []
+            response["warnings"] = warnings
         if bool(response.get("noop")):
             response["publish_requested"] = False
             response["publish_skipped"] = bool(publish)
@@ -3354,6 +3581,7 @@ class AiBuilderFacade:
         response["published"] = bool(publish_result.get("published"))
         verification["published"] = bool(publish_result.get("published"))
         if publish_result.get("status") == "failed":
+            warnings.append(_warning("PUBLISH_FAILED", "publish step failed after apply succeeded"))
             response["status"] = "partial_success"
             response["error_code"] = response.get("error_code") or publish_result.get("error_code")
             response["recoverable"] = True
@@ -3766,7 +3994,9 @@ def _failed(
         "backend_code": backend_code,
         "http_status": http_status,
         "noop": False,
+        "warnings": [],
         "verification": {},
+        "verified": False,
     }
 
 
@@ -3838,6 +4068,10 @@ def _from_stage_failure(stage: JSONObject, *, fallback_tool: str) -> JSONObject:
         "request_id": stage.get("request_id"),
         "backend_code": stage.get("backend_code"),
         "http_status": stage.get("http_status"),
+        "noop": False,
+        "warnings": [],
+        "verification": {},
+        "verified": False,
     }
 
 
@@ -4310,12 +4544,12 @@ def _normalize_backend_chart_type(value: Any) -> str:
     return by_code.get(raw, raw.lower())
 
 
-def _find_chart_by_name(items: Any, *, chart_name: str, chart_type: str | None = None) -> dict[str, Any] | None:
+def _find_charts_by_name(items: Any, *, chart_name: str, chart_type: str | None = None) -> list[dict[str, Any]]:
     target_name = str(chart_name or "").strip()
     target_type = _normalize_backend_chart_type(chart_type)
     candidates: list[dict[str, Any]] = []
     if not isinstance(items, list) or not target_name:
-        return None
+        return []
     for item in items:
         if not isinstance(item, dict):
             continue
@@ -4325,7 +4559,12 @@ def _find_chart_by_name(items: Any, *, chart_name: str, chart_type: str | None =
         item_type = _normalize_backend_chart_type(item.get("chartType"))
         if target_type and item_type and item_type != target_type:
             continue
-        candidates.append(item)
+        candidates.append(deepcopy(item))
+    return candidates
+
+
+def _find_chart_by_name(items: Any, *, chart_name: str, chart_type: str | None = None) -> dict[str, Any] | None:
+    candidates = _find_charts_by_name(items, chart_name=chart_name, chart_type=chart_type)
     if not candidates:
         return None
     return deepcopy(candidates[-1])
@@ -4402,15 +4641,25 @@ def _resolve_chart_reference(*, charts: QingbiReportTools, profile: str, ref: An
     chart_id = str(getattr(ref, "chart_id", "") or "").strip()
     chart_name = str(getattr(ref, "chart_name", "") or "").strip()
     items = charts.qingbi_report_list(profile=profile, app_key=app_key).get("items") or []
-    for item in items:
-        if not isinstance(item, dict):
-            continue
-        item_id = _extract_chart_identifier(item)
-        item_name = str(item.get("chartName") or "").strip()
-        if chart_id and item_id == chart_id:
-            return {"chart_id": item_id, "chart_name": item_name, "app_key": app_key}
-        if not chart_id and chart_name and item_name == chart_name:
-            return {"chart_id": item_id, "chart_name": item_name, "app_key": app_key}
+    if chart_id:
+        for item in items:
+            if not isinstance(item, dict):
+                continue
+            item_id = _extract_chart_identifier(item)
+            item_name = str(item.get("chartName") or "").strip()
+            if item_id == chart_id:
+                return {"chart_id": item_id, "chart_name": item_name, "app_key": app_key}
+        raise ValueError(f"chart ref chart_id '{chart_id}' could not be resolved under app '{app_key}'")
+    matches = _find_charts_by_name(items, chart_name=chart_name)
+    if len(matches) > 1:
+        raise ValueError(f"chart ref chart_name '{chart_name}' is ambiguous under app '{app_key}'; supply chart_id")
+    if len(matches) == 1:
+        item = matches[0]
+        return {
+            "chart_id": _extract_chart_identifier(item),
+            "chart_name": str(item.get("chartName") or "").strip(),
+            "app_key": app_key,
+        }
     raise ValueError(f"chart ref could not be resolved under app '{app_key}'")
 
 
@@ -4419,18 +4668,98 @@ def _resolve_view_reference(*, facade: AiBuilderFacade, profile: str, ref: Any)
     view_key = str(getattr(ref, "view_key", "") or "").strip()
     view_name = str(getattr(ref, "view_name", "") or "").strip()
     views, _ = facade._load_views_result(profile=profile, app_key=app_key, tolerate_404=False)
-    for item in views or []:
-        if not isinstance(item, dict):
-            continue
-        item_key = _extract_view_key(item)
-        item_name = _extract_view_name(item)
-        if view_key and item_key == view_key:
-            return {"view_key": item_key, "view_name": item_name, "app_key": app_key, "view_type": _normalize_portal_view_type(item)}
-        if not view_key and view_name and item_name == view_name:
-            return {"view_key": item_key, "view_name": item_name, "app_key": app_key, "view_type": _normalize_portal_view_type(item)}
+    if view_key:
+        for item in views or []:
+            if not isinstance(item, dict):
+                continue
+            item_key = _extract_view_key(item)
+            item_name = _extract_view_name(item)
+            if item_key == view_key:
+                return {"view_key": item_key, "view_name": item_name, "app_key": app_key, "view_type": _normalize_portal_view_type(item)}
+        raise ValueError(f"view ref view_key '{view_key}' could not be resolved under app '{app_key}'")
+    matched_items = [
+        item
+        for item in (views or [])
+        if isinstance(item, dict) and _extract_view_name(item) == view_name
+    ]
+    if len(matched_items) > 1:
+        raise ValueError(f"view ref view_name '{view_name}' is ambiguous under app '{app_key}'; supply view_key")
+    if len(matched_items) == 1:
+        item = matched_items[0]
+        return {
+            "view_key": _extract_view_key(item),
+            "view_name": _extract_view_name(item),
+            "app_key": app_key,
+            "view_type": _normalize_portal_view_type(item),
+        }
     raise ValueError(f"view ref could not be resolved under app '{app_key}'")
 
 
+def _verify_portal_readback(
+    *,
+    actual: Any,
+    expected_payload: dict[str, Any],
+    expected_section_count: int,
+    requested_config_keys: set[str],
+    verify_dash_name: bool,
+    verify_dash_icon: bool,
+    verify_auth: bool,
+    verify_hide_copyright: bool,
+    verify_dash_global_config: bool,
+    verify_tags: bool,
+) -> tuple[bool, list[str]]:
+    mismatches: list[str] = []
+    if not isinstance(actual, dict):
+        return False, ["portal readback payload is unavailable"]
+    components = actual.get("components")
+    if not isinstance(components, list) or len(components) != expected_section_count:
+        mismatches.append(f"components expected {expected_section_count}, got {len(components) if isinstance(components, list) else 'unavailable'}")
+    if verify_dash_name and str(actual.get("dashName") or "").strip() != str(expected_payload.get("dashName") or "").strip():
+        mismatches.append("dash_name")
+    if verify_dash_icon and str(actual.get("dashIcon") or "") != str(expected_payload.get("dashIcon") or ""):
+        mismatches.append("dash_icon")
+    if verify_auth and not _mapping_contains(actual.get("auth"), expected_payload.get("auth")):
+        mismatches.append("auth")
+    if verify_hide_copyright and bool(actual.get("hideCopyright", False)) != bool(expected_payload.get("hideCopyright", False)):
+        mismatches.append("hide_copyright")
+    if verify_dash_global_config and not _mapping_contains(actual.get("dashGlobalConfig") or {}, expected_payload.get("dashGlobalConfig") or {}):
+        mismatches.append("dash_global_config")
+    if verify_tags:
+        expected_tags = [
+            _coerce_positive_int((item or {}).get("tagId"))
+            for item in (expected_payload.get("tags") or [])
+            if isinstance(item, dict)
+        ]
+        actual_tags = [
+            _coerce_positive_int((item or {}).get("tagId"))
+            for item in (actual.get("tags") or [])
+            if isinstance(item, dict)
+        ]
+        if [item for item in expected_tags if item is not None] != [item for item in actual_tags if item is not None]:
+            mismatches.append("tags")
+    for key in sorted(requested_config_keys):
+        if deepcopy(actual.get(key)) != deepcopy(expected_payload.get(key)):
+            mismatches.append(f"config.{key}")
+    return not mismatches, mismatches
+
+
+def _mapping_contains(actual: Any, expected: Any) -> bool:
+    if isinstance(expected, dict):
+        if not isinstance(actual, dict):
+            return False
+        for key, expected_value in expected.items():
+            if key not in actual:
+                return False
+            if not _mapping_contains(actual.get(key), expected_value):
+                return False
+        return True
+    if isinstance(expected, list):
+        if not isinstance(actual, list) or len(actual) < len(expected):
+            return False
+        return all(_mapping_contains(actual[index], expected[index]) for index in range(len(expected)))
+    return deepcopy(actual) == deepcopy(expected)
+
+
 def _normalize_portal_view_type(view: dict[str, Any]) -> str:
     raw = str(view.get("viewgraphType") or view.get("type") or "").strip()
     mapping = {
@@ -4895,6 +5224,70 @@ def _build_verification_hints(
     return hints
 
 
+def _warning(code: str, message: str, **extra: Any) -> dict[str, Any]:
+    warning = {"code": code, "message": message}
+    warning.update({key: value for key, value in extra.items() if value is not None})
+    return warning
+
+
+def _warnings_from_verification_hints(hints: list[str]) -> list[dict[str, Any]]:
+    mapping = {
+        "package attachment not verified": _warning("PACKAGE_ATTACHMENT_UNVERIFIED", "package attachment is not verified"),
+        "layout has unplaced fields": _warning("LAYOUT_HAS_UNPLACED_FIELDS", "layout still contains unplaced fields"),
+        "no public views detected": _warning("NO_PUBLIC_VIEWS", "no public views were detected"),
+        "views_read_unavailable": _warning("VIEWS_READ_UNAVAILABLE", "views summary readback is unavailable"),
+        "workflow_read_unavailable": _warning("WORKFLOW_READ_UNAVAILABLE", "workflow summary readback is unavailable"),
+    }
+    return [deepcopy(mapping[hint]) for hint in hints if hint in mapping]
+
+
+def _layout_read_warnings(unplaced_fields: list[str]) -> list[dict[str, Any]]:
+    if not unplaced_fields:
+        return []
+    return [_warning("LAYOUT_HAS_UNPLACED_FIELDS", "layout still contains unplaced fields", fields=unplaced_fields)]
+
+
+def _publish_verify_warnings(*, package_attached: bool | None, views_unavailable: bool, verified: bool) -> list[dict[str, Any]]:
+    warnings: list[dict[str, Any]] = []
+    if package_attached is False:
+        warnings.append(_warning("PACKAGE_NOT_ATTACHED", "target package is not attached after publish verification"))
+    if views_unavailable:
+        warnings.append(_warning("VIEWS_READBACK_PENDING", "views readback is unavailable during publish verification"))
+    if not verified and not warnings:
+        warnings.append(_warning("PUBLISH_VERIFY_INCOMPLETE", "publish verification is incomplete"))
+    return warnings
+
+
+def _chart_apply_warnings(*, failed_items: list[dict[str, Any]], readback_unavailable: bool, verified: bool) -> list[dict[str, Any]]:
+    warnings: list[dict[str, Any]] = []
+    if failed_items:
+        warnings.append(_warning("CHART_OPERATION_FAILED", "one or more chart operations failed", failed_count=len(failed_items)))
+    if readback_unavailable:
+        warnings.append(_warning("CHART_READBACK_PENDING", "chart readback is unavailable after apply"))
+    elif not verified and not failed_items:
+        warnings.append(_warning("CHART_VERIFICATION_INCOMPLETE", "chart apply completed but verification is incomplete"))
+    return warnings
+
+
+def _portal_apply_warnings(
+    *,
+    publish_failed: bool,
+    draft_verified: bool,
+    draft_meta_verified: bool,
+    live_verified: bool | None,
+    live_meta_verified: bool | None,
+    publish_requested: bool,
+) -> list[dict[str, Any]]:
+    warnings: list[dict[str, Any]] = []
+    if publish_failed:
+        warnings.append(_warning("PORTAL_PUBLISH_FAILED", "portal publish failed after draft update"))
+    if not draft_verified or not draft_meta_verified:
+        warnings.append(_warning("PORTAL_DRAFT_VERIFICATION_INCOMPLETE", "portal draft verification is incomplete"))
+    if publish_requested and (live_verified is False or live_meta_verified is False):
+        warnings.append(_warning("PORTAL_LIVE_VERIFICATION_INCOMPLETE", "portal live verification is incomplete"))
+    return warnings
+
+
 def _build_layout_preset_sections(*, preset: LayoutPreset, field_names: list[str]) -> list[dict[str, Any]]:
     ordered = [name for name in field_names if name]
     if preset == LayoutPreset.single_section:
@@ -5281,6 +5674,108 @@ def _summarize_views(result: Any) -> list[dict[str, Any]]:
     return items
 
 
+def _summarize_charts(result: Any) -> list[dict[str, Any]]:
+    if not isinstance(result, list):
+        return []
+    items: list[dict[str, Any]] = []
+    for index, chart in enumerate(result):
+        if not isinstance(chart, dict):
+            continue
+        chart_id = _extract_chart_identifier(chart)
+        name = str(chart.get("chartName") or "").strip()
+        chart_type = _normalize_backend_chart_type(chart.get("chartType"))
+        if not any((chart_id, name, chart_type)):
+            continue
+        items.append(
+            {
+                "chart_id": chart_id or None,
+                "name": name or None,
+                "chart_type": chart_type or None,
+                "order": index,
+            }
+        )
+    return items
+
+
+def _summarize_portal_sections(components: Any) -> list[dict[str, Any]]:
+    if not isinstance(components, list):
+        return []
+    items: list[dict[str, Any]] = []
+    for index, component in enumerate(components):
+        if not isinstance(component, dict):
+            continue
+        source_type = _normalize_portal_component_source_type(component.get("type"))
+        title = _extract_portal_component_title(component, source_type=source_type)
+        summary: dict[str, Any] = {
+            "order": index,
+            "source_type": source_type,
+            "title": title,
+        }
+        position = component.get("position")
+        if isinstance(position, dict):
+            summary["position"] = deepcopy(position)
+        if source_type == "chart":
+            chart_config = component.get("chartConfig") if isinstance(component.get("chartConfig"), dict) else {}
+            summary["chart_ref"] = {
+                "chart_id": str(chart_config.get("biChartId") or "").strip() or None,
+                "chart_name": str(chart_config.get("chartComponentTitle") or title or "").strip() or None,
+            }
+        elif source_type == "view":
+            view_config = component.get("viewgraphConfig") if isinstance(component.get("viewgraphConfig"), dict) else {}
+            summary["view_ref"] = {
+                "app_key": str(view_config.get("appKey") or "").strip() or None,
+                "view_key": str(view_config.get("viewgraphKey") or "").strip() or None,
+                "view_name": str(view_config.get("viewgraphName") or title or "").strip() or None,
+            }
+        items.append(summary)
+    return items
+
+
+def _normalize_portal_component_source_type(value: Any) -> str:
+    raw = str(value or "").strip()
+    mapping = {
+        "2": "grid",
+        "4": "link",
+        "5": "text",
+        "6": "filter",
+        "9": "chart",
+        "10": "view",
+        "grid": "grid",
+        "link": "link",
+        "text": "text",
+        "filter": "filter",
+        "chart": "chart",
+        "view": "view",
+    }
+    return mapping.get(raw, raw.lower() or "unknown")
+
+
+def _extract_portal_component_title(component: dict[str, Any], *, source_type: str) -> str | None:
+    config_key_map = {
+        "grid": "gridConfig",
+        "link": "linkConfig",
+        "text": "textConfig",
+        "filter": "filterConfig",
+        "chart": "chartConfig",
+        "view": "viewgraphConfig",
+    }
+    config_key = config_key_map.get(source_type, "")
+    config = component.get(config_key) if isinstance(component.get(config_key), dict) else {}
+    title_candidates = {
+        "grid": ["gridTitle"],
+        "link": ["title", "linkTitle"],
+        "text": ["title", "textTitle"],
+        "filter": ["title", "filterTitle"],
+        "chart": ["chartComponentTitle", "componentTitle", "title"],
+        "view": ["componentTitle", "viewgraphName", "title"],
+    }
+    for key in title_candidates.get(source_type, []):
+        title = str(config.get(key) or "").strip()
+        if title:
+            return title
+    return None
+
+
 def _entity_spec_from_app(*, base_info: dict[str, Any], schema: dict[str, Any], views: Any) -> dict[str, Any]:
     parsed = _parse_schema(schema)
     fields = []