@josephyan/qingflow-cli 0.2.0-beta.82 → 0.2.0-beta.84

package/src/qingflow_mcp/builder_facade/service.py

@@ -406,30 +406,59 @@ class AiBuilderFacade:
             "visibility": _public_visibility_from_member_auth(desired_auth),
         }
 
-    def package_get(self, *, profile: str, tag_id: int) -> JSONObject:
-        normalized_args = {"tag_id": tag_id}
-        if _coerce_positive_int(tag_id) is None:
-            return _failed("TAG_ID_REQUIRED", "tag_id must be positive", normalized_args=normalized_args, suggested_next_call=None)
+    def package_get(self, *, profile: str, package_id: int | None = None, tag_id: int | None = None) -> JSONObject:
+        effective_package_id = _coerce_positive_int(package_id if package_id is not None else tag_id)
+        normalized_args = {"package_id": effective_package_id or package_id or tag_id}
+        if effective_package_id is None:
+            return _failed(
+                "PACKAGE_ID_REQUIRED",
+                "package_id must be positive",
+                normalized_args=normalized_args,
+                suggested_next_call=None,
+            )
+        base_result: JSONObject
         try:
-            detail_result = self.packages.package_get(profile=profile, tag_id=tag_id, include_raw=True)
-            base_result = self.packages.package_get_base(profile=profile, tag_id=tag_id, include_raw=True)
+            base_result = self.packages.package_get_base(profile=profile, tag_id=effective_package_id, include_raw=True)
         except (QingflowApiError, RuntimeError) as error:
             api_error = _coerce_api_error(error)
             return _failed_from_api_error(
                 "PACKAGE_GET_FAILED",
                 api_error,
                 normalized_args=normalized_args,
-                details={"tag_id": tag_id},
-                suggested_next_call={"tool_name": "package_get", "arguments": {"profile": profile, "tag_id": tag_id}},
+                details={"package_id": effective_package_id},
+                suggested_next_call={"tool_name": "package_get", "arguments": {"profile": profile, "package_id": effective_package_id}},
             )
-        detail = detail_result.get("result") if isinstance(detail_result.get("result"), dict) else {}
+
+        detail_result: JSONObject | None = None
+        detail_read_error: QingflowApiError | None = None
+        try:
+            detail_result = self.packages.package_get(profile=profile, tag_id=effective_package_id, include_raw=True)
+        except (QingflowApiError, RuntimeError) as error:
+            detail_read_error = _coerce_api_error(error)
+
+        detail = detail_result.get("result") if isinstance(detail_result, dict) and isinstance(detail_result.get("result"), dict) else {}
         base = base_result.get("result") if isinstance(base_result.get("result"), dict) else {}
-        summary = detail_result.get("summary") if isinstance(detail_result.get("summary"), dict) else {}
+        summary = detail_result.get("summary") if isinstance(detail_result, dict) and isinstance(detail_result.get("summary"), dict) else {}
+        source = detail if detail else base
+        warnings: list[JSONObject] = []
+        if detail_read_error is not None:
+            warnings.append(
+                {
+                    "code": "PACKAGE_DETAIL_READ_DEGRADED",
+                    "message": "package_get used baseInfo because the package detail endpoint was not readable",
+                    "backend_code": detail_read_error.backend_code,
+                    "http_status": detail_read_error.http_status,
+                }
+            )
+        public_items = _public_package_items_from_tag_items(source.get("tagItems") or base.get("tagItems"))
+        item_count = summary.get("itemCount")
+        if not isinstance(item_count, int) or item_count < 0 or (item_count == 0 and public_items):
+            item_count = len(public_items)
         return {
             "status": "success",
             "error_code": None,
             "recoverable": False,
-            "message": "read package detail",
+            "message": "read package",
             "normalized_args": normalized_args,
             "missing_fields": [],
             "allowed_values": {},
@@ -437,21 +466,183 @@ class AiBuilderFacade:
             "request_id": None,
             "suggested_next_call": None,
             "noop": False,
-            "warnings": [],
+            "warnings": warnings,
             "verification": {"package_exists": True},
             "verified": True,
-            "tag_id": _coerce_positive_int(detail.get("tagId") or base.get("tagId")) or tag_id,
-            "tag_name": str(detail.get("tagName") or base.get("tagName") or "").strip() or None,
-            "tag_icon": str(detail.get("tagIcon") or base.get("tagIcon") or "").strip() or None,
-            "publish_status": detail.get("publishStatus") if detail.get("publishStatus") is not None else base.get("publishStatus"),
-            "item_count": summary.get("itemCount"),
-            "item_preview": deepcopy(summary.get("itemPreview") or []),
+            "package_id": _coerce_positive_int(source.get("tagId") or base.get("tagId")) or effective_package_id,
+            "package_name": str(source.get("tagName") or base.get("tagName") or "").strip() or None,
+            "icon": str(source.get("tagIcon") or base.get("tagIcon") or "").strip() or None,
+            "publish_status": source.get("publishStatus") if source.get("publishStatus") is not None else base.get("publishStatus"),
+            "item_count": item_count,
             "add_app_status": base.get("addAppStatus") if base.get("addAppStatus") is not None else summary.get("addAppStatus"),
             "edit_app_status": base.get("editAppStatus") if base.get("editAppStatus") is not None else summary.get("editAppStatus"),
             "del_app_status": base.get("delAppStatus") if base.get("delAppStatus") is not None else summary.get("delAppStatus"),
             "edit_tag_status": base.get("editTagStatus") if base.get("editTagStatus") is not None else summary.get("editTagStatus"),
-            "visibility": _public_visibility_from_member_auth(base.get("auth") or detail.get("auth")),
+            "visibility": _public_visibility_from_member_auth(base.get("auth") or source.get("auth")),
+            "items": public_items,
+        }
+
+    def package_apply(
+        self,
+        *,
+        profile: str,
+        package_id: int | None = None,
+        package_name: str | None = None,
+        create_if_missing: bool = False,
+        icon: str | None = None,
+        color: str | None = None,
+        visibility: VisibilityPatch | None = None,
+        items: list[dict[str, Any]] | None = None,
+        allow_detach: bool = False,
+    ) -> JSONObject:
+        requested_name = str(package_name or "").strip()
+        normalized_args: JSONObject = {
+            "package_id": package_id,
+            **({"package_name": requested_name} if requested_name else {}),
+            "create_if_missing": bool(create_if_missing),
+            **({"icon": icon} if icon else {}),
+            **({"color": color} if color else {}),
+            **({"visibility": visibility.model_dump(mode="json")} if visibility is not None else {}),
+            **({"items": deepcopy(items)} if items is not None else {}),
+            "allow_detach": bool(allow_detach),
+        }
+        effective_package_id = _coerce_positive_int(package_id)
+        created = False
+        permission_outcomes: list[PermissionCheckOutcome] = []
+
+        if effective_package_id is None:
+            if not create_if_missing:
+                return _failed(
+                    "PACKAGE_ID_REQUIRED",
+                    "package_id is required unless create_if_missing=true",
+                    normalized_args=normalized_args,
+                    suggested_next_call=None,
+                )
+            if not requested_name:
+                return _failed(
+                    "PACKAGE_NAME_REQUIRED",
+                    "package_name is required when create_if_missing=true",
+                    normalized_args=normalized_args,
+                    suggested_next_call=None,
+                )
+            create_result = self.package_create(
+                profile=profile,
+                package_name=requested_name,
+                icon=icon,
+                color=color,
+                visibility=visibility,
+            )
+            if create_result.get("status") not in {"success", "partial_success"}:
+                return _publicize_package_apply_failure(create_result, profile=profile, normalized_args=normalized_args)
+            effective_package_id = _coerce_positive_int(create_result.get("tag_id") or create_result.get("package_id"))
+            if effective_package_id is None:
+                return _failed(
+                    "PACKAGE_CREATE_UNVERIFIED",
+                    "created package but could not verify package_id",
+                    normalized_args=normalized_args,
+                    details={"create_result": create_result},
+                    suggested_next_call={"tool_name": "package_get", "arguments": {"profile": profile, "package_id": package_id}},
+                )
+            normalized_args["package_id"] = effective_package_id
+            created = True
+
+        metadata_requested = bool(requested_name or icon or color or visibility is not None)
+        if metadata_requested and not created:
+            edit_tag_outcome = self._guard_package_permission(
+                profile=profile,
+                tag_id=effective_package_id,
+                required_permission="edit_tag",
+                normalized_args=normalized_args,
+            )
+            if edit_tag_outcome.block is not None:
+                return edit_tag_outcome.block
+            permission_outcomes.append(edit_tag_outcome)
+            update_result = self.package_update(
+                profile=profile,
+                tag_id=effective_package_id,
+                package_name=requested_name or None,
+                icon=icon,
+                color=color,
+                visibility=visibility,
+            )
+            if update_result.get("status") not in {"success", "partial_success"}:
+                return _publicize_package_apply_failure(update_result, profile=profile, normalized_args=normalized_args)
+
+        layout_result: JSONObject | None = None
+        if items is not None:
+            if not isinstance(items, list):
+                return _failed(
+                    "PACKAGE_ITEMS_INVALID",
+                    "items must be a list",
+                    normalized_args=normalized_args,
+                    suggested_next_call=None,
+                )
+            layout_result = self._apply_package_items(
+                profile=profile,
+                package_id=effective_package_id,
+                items=items,
+                allow_detach=allow_detach,
+                normalized_args=normalized_args,
+            )
+            if layout_result.get("status") not in {"success", "partial_success"}:
+                return _apply_permission_outcomes(layout_result, *permission_outcomes)
+
+        verification = self.package_get(profile=profile, package_id=effective_package_id)
+        if verification.get("status") != "success":
+            return _apply_permission_outcomes(verification, *permission_outcomes)
+        expected_visibility = None
+        if visibility is not None:
+            try:
+                expected_visibility = _public_visibility_from_member_auth(
+                    self._compile_visibility_to_member_auth(profile=profile, visibility=visibility)
+                )
+            except VisibilityResolutionError:
+                expected_visibility = None
+        response: JSONObject = {
+            "status": "success",
+            "error_code": None,
+            "recoverable": False,
+            "message": "applied package",
+            "normalized_args": normalized_args,
+            "missing_fields": [],
+            "allowed_values": {},
+            "details": {"layout_result": layout_result} if layout_result is not None else {},
+            "request_id": None,
+            "suggested_next_call": None,
+            "noop": not (created or metadata_requested or items is not None),
+            "warnings": [],
+            "verification": {
+                "package_exists": True,
+                "package_created": created,
+                "layout_applied": items is not None,
+                "visibility_verified": None
+                if expected_visibility is None
+                else _visibility_matches_expected(verification.get("visibility"), expected_visibility),
+            },
+            "verified": True,
+            **{
+                key: deepcopy(value)
+                for key, value in verification.items()
+                if key
+                not in {
+                    "status",
+                    "error_code",
+                    "recoverable",
+                    "message",
+                    "normalized_args",
+                    "missing_fields",
+                    "allowed_values",
+                    "details",
+                    "request_id",
+                    "suggested_next_call",
+                    "noop",
+                    "warnings",
+                    "verification",
+                    "verified",
+                }
+            },
         }
+        return _apply_permission_outcomes(response, *permission_outcomes)
 
     def package_update(
         self,
@@ -524,7 +715,7 @@ class AiBuilderFacade:
                 details={"tag_id": tag_id},
                 suggested_next_call={"tool_name": "package_update", "arguments": {"profile": profile, **normalized_args}},
             )
-        verification = self.package_get(profile=profile, tag_id=tag_id)
+        verification = self.package_get(profile=profile, package_id=tag_id)
         if verification.get("status") != "success":
             return verification
         return {
@@ -648,6 +839,217 @@ class AiBuilderFacade:
             "retried": bool(listed.get("retried", False)),
         }
 
+    def _apply_package_items(
+        self,
+        *,
+        profile: str,
+        package_id: int,
+        items: list[dict[str, Any]],
+        allow_detach: bool,
+        normalized_args: JSONObject,
+    ) -> JSONObject:
+        current_result: JSONObject | None = None
+        try:
+            current_result = self.packages.package_get(profile=profile, tag_id=package_id, include_raw=True)
+        except (QingflowApiError, RuntimeError) as detail_error:
+            detail_api_error = _coerce_api_error(detail_error)
+            try:
+                current_result = self.packages.package_get_base(profile=profile, tag_id=package_id, include_raw=True)
+            except (QingflowApiError, RuntimeError) as base_error:
+                api_error = _coerce_api_error(base_error)
+                return _failed_from_api_error(
+                    "PACKAGE_LAYOUT_READ_FAILED",
+                    api_error,
+                    normalized_args=normalized_args,
+                    details={
+                        "package_id": package_id,
+                        "detail_read_error": _transport_error_payload(detail_api_error),
+                    },
+                    suggested_next_call={"tool_name": "package_get", "arguments": {"profile": profile, "package_id": package_id}},
+                )
+        current_raw = current_result.get("result") if isinstance(current_result.get("result"), dict) else {}
+        raw_tag_items = current_raw.get("tagItems")
+        if not isinstance(raw_tag_items, list):
+            return _failed(
+                "PACKAGE_LAYOUT_UNREADABLE",
+                "package items could not be read safely",
+                normalized_args=normalized_args,
+                details={"package_id": package_id},
+                suggested_next_call={"tool_name": "package_get", "arguments": {"profile": profile, "package_id": package_id}},
+            )
+        current_items = raw_tag_items
+
+        current_group_specs = _collect_backend_package_group_specs(current_items)
+        normalized_items, group_resolution_issues = _align_public_package_group_ids(items, current_group_specs=current_group_specs)
+        if group_resolution_issues:
+            return _failed(
+                "PACKAGE_GROUP_AMBIGUOUS",
+                "items contains group names that match multiple existing package groups; pass explicit group_id to disambiguate",
+                normalized_args=normalized_args,
+                details={"package_id": package_id, "issues": group_resolution_issues},
+                suggested_next_call={"tool_name": "package_get", "arguments": {"profile": profile, "package_id": package_id}},
+            )
+
+        current_resources = _flatten_package_resource_identities(current_items, public=False)
+        desired_resources = _flatten_package_resource_identities(normalized_items, public=True)
+        missing_resources = sorted(current_resources - desired_resources)
+        if missing_resources and not allow_detach:
+            return _failed(
+                "PACKAGE_LAYOUT_ITEMS_MISSING",
+                "items omits existing apps or portals; pass allow_detach=true to remove them",
+                normalized_args=normalized_args,
+                details={"package_id": package_id, "missing_items": [{"type": item[0], "id": item[1]} for item in missing_resources]},
+                suggested_next_call=None,
+            )
+
+        duplicate_resources = _find_duplicate_package_resources(normalized_items)
+        if duplicate_resources:
+            return _failed(
+                "PACKAGE_LAYOUT_DUPLICATE_ITEM",
+                "items contains duplicate apps or portals",
+                normalized_args=normalized_args,
+                details={"duplicates": [{"type": item[0], "id": item[1]} for item in duplicate_resources]},
+                suggested_next_call=None,
+            )
+
+        current_groups = {int(spec["group_id"]): str(spec["name"] or "").strip() for spec in current_group_specs}
+        desired_groups = _collect_public_package_group_specs(normalized_items)
+        desired_group_ids = {
+            group_id for group_id in (_coerce_positive_int(group.get("group_id")) for group in desired_groups) if group_id is not None
+        }
+        deleted_group_ids = sorted(set(current_groups) - desired_group_ids)
+
+        permission_outcomes: list[PermissionCheckOutcome] = []
+        needs_group_create = any(_coerce_positive_int(group.get("group_id")) is None for group in desired_groups)
+        needs_group_delete = bool(deleted_group_ids)
+        needs_edit_app = bool(normalized_items)
+        for required_permission in (
+            (["add_app"] if needs_group_create else [])
+            + (["edit_app"] if needs_edit_app else [])
+            + (["delete_app"] if needs_group_delete else [])
+        ):
+            outcome = self._guard_package_permission(
+                profile=profile,
+                tag_id=package_id,
+                required_permission=required_permission,
+                normalized_args=normalized_args,
+            )
+            if outcome.block is not None:
+                return outcome.block
+            permission_outcomes.append(outcome)
+
+        group_ids_by_path: dict[tuple[int, ...], int] = {}
+        group_operations: list[JSONObject] = []
+        for group in desired_groups:
+            path = tuple(group.get("path") or ())
+            group_id = _coerce_positive_int(group.get("group_id"))
+            group_name = str(group.get("name") or "").strip()
+            if not group_name:
+                return _failed(
+                    "PACKAGE_GROUP_NAME_REQUIRED",
+                    "group items require name",
+                    normalized_args=normalized_args,
+                    details={"path": list(path)},
+                    suggested_next_call=None,
+                )
+            if group_id is None:
+                try:
+                    created = self.packages.package_group_create(profile=profile, tag_id=package_id, group_name=group_name)
+                except (QingflowApiError, RuntimeError) as error:
+                    api_error = _coerce_api_error(error)
+                    return _failed_from_api_error(
+                        "PACKAGE_GROUP_CREATE_FAILED",
+                        api_error,
+                        normalized_args=normalized_args,
+                        details={"package_id": package_id, "group_name": group_name},
+                        suggested_next_call=None,
+                    )
+                group_id = _extract_package_group_id(created)
+                if group_id is None:
+                    return _failed(
+                        "PACKAGE_GROUP_CREATE_UNVERIFIED",
+                        "created package group but could not read group_id",
+                        normalized_args=normalized_args,
+                        details={"package_id": package_id, "group_name": group_name, "create_result": created},
+                        suggested_next_call={"tool_name": "package_get", "arguments": {"profile": profile, "package_id": package_id}},
+                    )
+                group_operations.append({"action": "create", "group_id": group_id, "name": group_name})
+            elif current_groups.get(group_id) != group_name:
+                try:
+                    self.packages.package_group_update(profile=profile, tag_id=package_id, group_id=group_id, group_name=group_name)
+                except (QingflowApiError, RuntimeError) as error:
+                    api_error = _coerce_api_error(error)
+                    return _failed_from_api_error(
+                        "PACKAGE_GROUP_UPDATE_FAILED",
+                        api_error,
+                        normalized_args=normalized_args,
+                        details={"package_id": package_id, "group_id": group_id, "group_name": group_name},
+                        suggested_next_call=None,
+                    )
+                group_operations.append({"action": "update", "group_id": group_id, "name": group_name})
+            group_ids_by_path[path] = group_id
+
+        try:
+            backend_items = _backend_package_items_from_public_items(normalized_items, group_ids_by_path)
+        except ValueError as error:
+            return _failed(
+                "PACKAGE_LAYOUT_INVALID",
+                str(error),
+                normalized_args=normalized_args,
+                details={"package_id": package_id},
+                suggested_next_call=None,
+            )
+
+        try:
+            sort_result = self.packages.package_sort_items(profile=profile, tag_id=package_id, tag_items=backend_items)
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _failed_from_api_error(
+                "PACKAGE_LAYOUT_SORT_FAILED",
+                api_error,
+                normalized_args=normalized_args,
+                details={"package_id": package_id},
+                suggested_next_call=None,
+            )
+
+        for group_id in deleted_group_ids:
+            try:
+                self.packages.package_group_delete(profile=profile, tag_id=package_id, group_id=group_id)
+            except (QingflowApiError, RuntimeError) as error:
+                api_error = _coerce_api_error(error)
+                return _apply_permission_outcomes(
+                    _failed_from_api_error(
+                        "PACKAGE_GROUP_DELETE_FAILED",
+                        api_error,
+                        normalized_args=normalized_args,
+                        details={"package_id": package_id, "group_id": group_id},
+                        suggested_next_call=None,
+                    ),
+                    *permission_outcomes,
+                )
+            group_operations.append({"action": "delete", "group_id": group_id})
+
+        return _apply_permission_outcomes(
+            {
+                "status": "success",
+                "error_code": None,
+                "recoverable": False,
+                "message": "applied package items",
+                "normalized_args": normalized_args,
+                "missing_fields": [],
+                "allowed_values": {},
+                "details": {"group_operations": group_operations, "sort_result": sort_result},
+                "request_id": sort_result.get("request_id") if isinstance(sort_result, dict) else None,
+                "suggested_next_call": None,
+                "noop": False,
+                "warnings": [],
+                "verification": {"layout_applied": True},
+                "verified": True,
+                "package_id": package_id,
+            },
+            *permission_outcomes,
+        )
+
     def member_search(self, *, profile: str, query: str, page_num: int = 1, page_size: int = 20, contain_disable: bool = False) -> JSONObject:
         requested = str(query or "").strip()
         normalized_args = {
@@ -2505,6 +2907,11 @@ class AiBuilderFacade:
                 "PACKAGE_EDIT_APP_UNAUTHORIZED",
                 "current user does not have package edit-app permission on this package",
             ),
+            "delete_app": (
+                "can_delete_app",
+                "PACKAGE_DELETE_APP_UNAUTHORIZED",
+                "current user does not have package delete-app permission on this package",
+            ),
             "edit_tag": (
                 "can_edit_tag",
                 "PACKAGE_EDIT_TAG_UNAUTHORIZED",
@@ -11904,6 +12311,358 @@ def _tag_items_include_app(tag_items: Any, app_key: str) -> bool:
     return any(str(item.get("appKey") or "") == app_key for item in tag_items if isinstance(item, dict))
 
 
+def _public_package_items_from_tag_items(tag_items: Any) -> list[JSONObject]:
+    if not isinstance(tag_items, list):
+        return []
+    public_items: list[JSONObject] = []
+    for item in tag_items:
+        if not isinstance(item, dict):
+            continue
+        item_type = _coerce_positive_int(item.get("itemType"))
+        if item_type == 1:
+            app_key = str(item.get("appKey") or "").strip()
+            if not app_key:
+                continue
+            public_items.append(
+                _compact_dict(
+                    {
+                        "type": "app",
+                        "app_key": app_key,
+                        "title": str(item.get("title") or item.get("formTitle") or "").strip() or None,
+                        "form_id": item.get("formId"),
+                    }
+                )
+            )
+            continue
+        if item_type == 2:
+            dash_key = str(item.get("dashKey") or item.get("pageKey") or "").strip()
+            if not dash_key:
+                continue
+            public_items.append(
+                _compact_dict(
+                    {
+                        "type": "portal",
+                        "dash_key": dash_key,
+                        "title": str(item.get("title") or item.get("dashName") or "").strip() or None,
+                    }
+                )
+            )
+            continue
+        if item_type == 3:
+            group_id = _coerce_positive_int(item.get("groupId"))
+            public_items.append(
+                _compact_dict(
+                    {
+                        "type": "group",
+                        "group_id": group_id,
+                        "name": str(item.get("title") or item.get("groupName") or "").strip() or None,
+                        "items": _public_package_items_from_tag_items(item.get("subItems")),
+                    }
+                )
+            )
+    return public_items
+
+
+def _flatten_package_resource_identities(items: Any, *, public: bool) -> set[tuple[str, str]]:
+    flattened: set[tuple[str, str]] = set()
+
+    def walk(value: Any) -> None:
+        if isinstance(value, list):
+            for child in value:
+                walk(child)
+            return
+        if not isinstance(value, dict):
+            return
+        if public:
+            item_type = str(value.get("type") or "").strip().lower()
+            if item_type == "app" or value.get("app_key") or value.get("appKey"):
+                app_key = str(value.get("app_key") or value.get("appKey") or "").strip()
+                if app_key:
+                    flattened.add(("app", app_key))
+            elif item_type == "portal" or value.get("dash_key") or value.get("dashKey"):
+                dash_key = str(value.get("dash_key") or value.get("dashKey") or "").strip()
+                if dash_key:
+                    flattened.add(("portal", dash_key))
+            walk(value.get("items"))
+            return
+        item_type = _coerce_positive_int(value.get("itemType"))
+        if item_type == 1:
+            app_key = str(value.get("appKey") or "").strip()
+            if app_key:
+                flattened.add(("app", app_key))
+        elif item_type == 2:
+            dash_key = str(value.get("dashKey") or value.get("pageKey") or "").strip()
+            if dash_key:
+                flattened.add(("portal", dash_key))
+        walk(value.get("subItems"))
+
+    walk(items)
+    return flattened
+
+
+def _find_duplicate_package_resources(items: Any) -> list[tuple[str, str]]:
+    seen: set[tuple[str, str]] = set()
+    duplicates: set[tuple[str, str]] = set()
+
+    def walk(value: Any) -> None:
+        if isinstance(value, list):
+            for child in value:
+                walk(child)
+            return
+        if not isinstance(value, dict):
+            return
+        item_type = str(value.get("type") or "").strip().lower()
+        identity: tuple[str, str] | None = None
+        if item_type == "app" or value.get("app_key") or value.get("appKey"):
+            app_key = str(value.get("app_key") or value.get("appKey") or "").strip()
+            if app_key:
+                identity = ("app", app_key)
+        elif item_type == "portal" or value.get("dash_key") or value.get("dashKey"):
+            dash_key = str(value.get("dash_key") or value.get("dashKey") or "").strip()
+            if dash_key:
+                identity = ("portal", dash_key)
+        if identity is not None:
+            if identity in seen:
+                duplicates.add(identity)
+            seen.add(identity)
+        walk(value.get("items"))
+
+    walk(items)
+    return sorted(duplicates)
+
+
+def _collect_backend_package_groups(tag_items: Any) -> dict[int, str]:
+    return {
+        int(spec["group_id"]): str(spec["name"] or "").strip()
+        for spec in _collect_backend_package_group_specs(tag_items)
+        if _coerce_positive_int(spec.get("group_id")) is not None
+    }
+
+
+def _collect_backend_package_group_specs(tag_items: Any, *, path: tuple[int, ...] = ()) -> list[JSONObject]:
+    if not isinstance(tag_items, list):
+        return []
+    groups: list[JSONObject] = []
+    for index, item in enumerate(tag_items):
+        if not isinstance(item, dict):
+            continue
+        item_type = _coerce_positive_int(item.get("itemType"))
+        child_path = (*path, index)
+        if item_type == 3:
+            group_id = _coerce_positive_int(item.get("groupId"))
+            if group_id is None:
+                continue
+            child_items = item.get("subItems") if isinstance(item.get("subItems"), list) else []
+            groups.append(
+                {
+                    "path": list(child_path),
+                    "group_id": group_id,
+                    "name": str(item.get("title") or item.get("groupName") or "").strip(),
+                    "resource_signature": _package_resource_signature(child_items, public=False),
+                }
+            )
+            groups.extend(_collect_backend_package_group_specs(child_items, path=child_path))
+    return groups
+
+
+def _collect_public_package_group_specs(items: Any, *, path: tuple[int, ...] = ()) -> list[JSONObject]:
+    if not isinstance(items, list):
+        return []
+    groups: list[JSONObject] = []
+    for index, item in enumerate(items):
+        if not isinstance(item, dict):
+            continue
+        item_type = str(item.get("type") or "").strip().lower()
+        child_path = (*path, index)
+        if item_type == "group" or isinstance(item.get("items"), list):
+            groups.append(
+                {
+                    "path": list(child_path),
+                    "group_id": _coerce_positive_int(item.get("group_id") or item.get("groupId")),
+                    "name": str(item.get("name") or item.get("title") or item.get("group_name") or "").strip(),
+                }
+            )
+            groups.extend(_collect_public_package_group_specs(item.get("items"), path=child_path))
+    return groups
+
+
+def _align_public_package_group_ids(
+    items: list[dict[str, Any]],
+    *,
+    current_group_specs: list[JSONObject],
+) -> tuple[list[dict[str, Any]], list[JSONObject]]:
+    normalized_items = deepcopy(items)
+    used_group_ids: set[int] = set()
+    issues: list[JSONObject] = []
+
+    def walk(nodes: list[dict[str, Any]], *, path: tuple[int, ...] = ()) -> None:
+        for index, node in enumerate(nodes):
+            if not isinstance(node, dict):
+                continue
+            item_type = str(node.get("type") or "").strip().lower()
+            child_path = (*path, index)
+            child_items = node.get("items") if isinstance(node.get("items"), list) else []
+            if item_type == "group" or isinstance(node.get("items"), list):
+                explicit_group_id = _coerce_positive_int(node.get("group_id") or node.get("groupId"))
+                if explicit_group_id is not None:
+                    node["group_id"] = explicit_group_id
+                    used_group_ids.add(explicit_group_id)
+                else:
+                    group_name = str(node.get("name") or node.get("title") or node.get("group_name") or "").strip()
+                    matched_group, ambiguity = _match_existing_package_group(
+                        group_name=group_name,
+                        child_items=child_items,
+                        path=child_path,
+                        current_group_specs=current_group_specs,
+                        used_group_ids=used_group_ids,
+                    )
+                    if ambiguity is not None:
+                        issues.append(ambiguity)
+                    elif matched_group is not None:
+                        matched_group_id = _coerce_positive_int(matched_group.get("group_id"))
+                        if matched_group_id is not None:
+                            node["group_id"] = matched_group_id
+                            used_group_ids.add(matched_group_id)
+                walk(child_items, path=child_path)
+
+    walk(normalized_items)
+    return normalized_items, issues
+
+
+def _match_existing_package_group(
+    *,
+    group_name: str,
+    child_items: list[dict[str, Any]],
+    path: tuple[int, ...],
+    current_group_specs: list[JSONObject],
+    used_group_ids: set[int],
+) -> tuple[JSONObject | None, JSONObject | None]:
+    desired_signature = _package_resource_signature(child_items, public=True)
+    candidates = [
+        spec
+        for spec in current_group_specs
+        if _coerce_positive_int(spec.get("group_id")) is not None
+        and int(spec["group_id"]) not in used_group_ids
+        and str(spec.get("name") or "").strip() == group_name
+    ]
+    exact_matches = [spec for spec in candidates if spec.get("resource_signature") == desired_signature]
+    if len(exact_matches) == 1:
+        return exact_matches[0], None
+    path_matches = [spec for spec in candidates if tuple(spec.get("path") or ()) == path]
+    if len(path_matches) == 1:
+        return path_matches[0], None
+    if len(candidates) == 1:
+        return candidates[0], None
+    ambiguous_matches = exact_matches if len(exact_matches) > 1 else candidates if len(candidates) > 1 else []
+    if ambiguous_matches:
+        return None, {
+            "path": list(path),
+            "name": group_name,
+            "candidate_group_ids": [
+                int(spec["group_id"])
+                for spec in ambiguous_matches
+                if _coerce_positive_int(spec.get("group_id")) is not None
+            ],
+        }
+    return None, None
+
+
+def _package_resource_signature(items: Any, *, public: bool) -> tuple[tuple[str, str], ...]:
+    return tuple(sorted(_flatten_package_resource_identities(items, public=public)))
+
+
+def _backend_package_items_from_public_items(items: list[dict[str, Any]], group_ids_by_path: dict[tuple[int, ...], int], *, path: tuple[int, ...] = ()) -> list[JSONObject]:
+    backend_items: list[JSONObject] = []
+    for index, item in enumerate(items):
+        if not isinstance(item, dict):
+            raise ValueError(f"items[{index}] must be an object")
+        item_type = str(item.get("type") or "").strip().lower()
+        child_path = (*path, index)
+        if item_type == "app" or item.get("app_key") or item.get("appKey"):
+            app_key = str(item.get("app_key") or item.get("appKey") or "").strip()
+            if not app_key:
+                raise ValueError(f"items[{index}].app_key is required")
+            backend_items.append(
+                _compact_dict(
+                    {
+                        "itemType": 1,
+                        "appKey": app_key,
+                        "title": str(item.get("title") or item.get("name") or "").strip() or None,
+                        "formId": item.get("form_id") or item.get("formId"),
+                    }
+                )
+            )
+            continue
+        if item_type == "portal" or item.get("dash_key") or item.get("dashKey"):
+            dash_key = str(item.get("dash_key") or item.get("dashKey") or "").strip()
+            if not dash_key:
+                raise ValueError(f"items[{index}].dash_key is required")
+            backend_items.append(
+                _compact_dict(
+                    {
+                        "itemType": 2,
+                        "dashKey": dash_key,
+                        "title": str(item.get("title") or item.get("name") or "").strip() or None,
+                    }
+                )
+            )
+            continue
+        if item_type == "group" or isinstance(item.get("items"), list):
+            group_id = group_ids_by_path.get(child_path) or _coerce_positive_int(item.get("group_id") or item.get("groupId"))
+            if group_id is None:
+                raise ValueError(f"items[{index}].group_id is required after group creation")
+            group_name = str(item.get("name") or item.get("title") or item.get("group_name") or "").strip()
+            if not group_name:
+                raise ValueError(f"items[{index}].name is required")
+            child_items = item.get("items") if isinstance(item.get("items"), list) else []
+            backend_items.append(
+                {
+                    "itemType": 3,
+                    "groupId": group_id,
+                    "title": group_name,
+                    "subItems": _backend_package_items_from_public_items(child_items, group_ids_by_path, path=child_path),
+                }
+            )
+            continue
+        raise ValueError(f"items[{index}].type must be app, portal, or group")
+    return backend_items
+
+
+def _extract_package_group_id(value: Any) -> int | None:
+    if isinstance(value, dict):
+        direct = _coerce_positive_int(value.get("groupId") or value.get("group_id") or value.get("id"))
+        if direct is not None:
+            return direct
+        for nested_key in ("result", "data", "group"):
+            nested = value.get(nested_key)
+            nested_id = _extract_package_group_id(nested)
+            if nested_id is not None:
+                return nested_id
+    if isinstance(value, list):
+        for item in value:
+            nested_id = _extract_package_group_id(item)
+            if nested_id is not None:
+                return nested_id
+    return None
+
+
+def _publicize_package_apply_failure(result: JSONObject, *, profile: str, normalized_args: JSONObject) -> JSONObject:
+    public_result = deepcopy(result)
+    public_result["normalized_args"] = deepcopy(normalized_args)
+    suggested = public_result.get("suggested_next_call")
+    if isinstance(suggested, dict):
+        public_result["suggested_next_call"] = {
+            "tool_name": "package_apply",
+            "arguments": {"profile": profile, **deepcopy(normalized_args)},
+        }
+    for key in ("tag_id", "tag_name", "tag_icon"):
+        public_result.pop(key, None)
+    details = public_result.get("details")
+    if isinstance(details, dict) and "tag_id" in details:
+        details["package_id"] = details.pop("tag_id")
+    return public_result
+
+
 def _verify_package_attachment(packages: PackageTools, *, profile: str, tag_id: int, app_key: str, attempts: int = 2) -> JSONObject:
     last_result: JSONObject = {"result": {}}
     for _ in range(max(attempts, 1)):