kaiten-cli 0.3.3__py3-none-any.whl

kaiten_cli/runtime/support/projects.py

@@ -0,0 +1,66 @@
+"""Project-specific execution helpers."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from kaiten_cli.errors import ApiError
+from kaiten_cli.i18n import tr
+from kaiten_cli.models import DebugReporter
+from kaiten_cli.runtime.client import KaitenClient
+
+
+def extract_project_cards(payload: Any) -> list[Any] | None:
+    if not isinstance(payload, dict):
+        return None
+
+    direct_cards = payload.get("cards")
+    if isinstance(direct_cards, list):
+        return direct_cards
+
+    direct_cards_data = payload.get("cards_data")
+    if isinstance(direct_cards_data, list):
+        return direct_cards_data
+
+    project_payload = payload.get("project")
+    if isinstance(project_payload, dict):
+        nested_cards = project_payload.get("cards")
+        if isinstance(nested_cards, list):
+            return nested_cards
+        nested_cards_data = project_payload.get("cards_data")
+        if isinstance(nested_cards_data, list):
+            return nested_cards_data
+
+    return None
+
+
+async def fetch_project_cards(
+    client: KaitenClient,
+    project_id: str,
+    *,
+    timeout: float,
+    reporter: DebugReporter | None = None,
+) -> list[Any]:
+    try:
+        result = await client.get(f"/projects/{project_id}/cards", timeout=timeout)
+        if isinstance(result, list):
+            return result
+        return []
+    except ApiError as exc:
+        if exc.status_code != 405:
+            raise
+        if reporter is not None:
+            reporter(
+                tr(
+                    "fallback: GET /projects/{id}/cards returned 405, retrying with with_cards_data=true"
+                )
+            )
+        project = await client.get(
+            f"/projects/{project_id}",
+            params={"with_cards_data": True},
+            timeout=timeout,
+        )
+        cards = extract_project_cards(project)
+        if cards is None:
+            raise exc
+        return cards

kaiten_cli/runtime/support/relations.py

@@ -0,0 +1,86 @@
+"""Support helpers for relation- and comment-heavy investigations."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from kaiten_cli.runtime.support.batch import (
+    DEFAULT_BATCH_WORKERS,
+    fetch_card_collection_batch,
+)
+from kaiten_cli.runtime.support.pagination import (
+    API_MAX_PAGE_SIZE,
+    DEFAULT_COLLECTION_MAX_PAGES,
+)
+from kaiten_cli.runtime.transforms import compact_response, select_fields
+
+
+def _shape_nested_items(items: list[Any], *, compact: bool, fields: str | None) -> list[Any]:
+    shaped = compact_response(items, compact)
+    return select_fields(shaped, fields)
+
+
+async def fetch_card_children_batch(
+    *,
+    domain: str,
+    token: str,
+    card_ids: list[int],
+    workers: int = DEFAULT_BATCH_WORKERS,
+    page_size: int = API_MAX_PAGE_SIZE,
+    max_pages: int = DEFAULT_COLLECTION_MAX_PAGES,
+    compact: bool = False,
+    fields: str | None = None,
+    timeout: float,
+    reporter,
+    execution_context=None,
+    cache_policy: str = "request_scope",
+) -> dict[str, Any]:
+    return await fetch_card_collection_batch(
+        domain=domain,
+        token=token,
+        card_ids=card_ids,
+        workers=workers,
+        timeout=timeout,
+        reporter=reporter,
+        execution_context=execution_context,
+        cache_policy=cache_policy,
+        path_for_card=lambda card_id: f"/cards/{card_id}/children",
+        page_size=page_size,
+        max_pages=max_pages,
+        result_field="children",
+        transform_items=lambda items: _shape_nested_items(items, compact=compact, fields=fields),
+        worker_label="batch-children",
+    )
+
+
+async def fetch_comments_batch(
+    *,
+    domain: str,
+    token: str,
+    card_ids: list[int],
+    workers: int = DEFAULT_BATCH_WORKERS,
+    page_size: int = API_MAX_PAGE_SIZE,
+    max_pages: int = DEFAULT_COLLECTION_MAX_PAGES,
+    compact: bool = False,
+    fields: str | None = None,
+    timeout: float,
+    reporter,
+    execution_context=None,
+    cache_policy: str = "request_scope",
+) -> dict[str, Any]:
+    return await fetch_card_collection_batch(
+        domain=domain,
+        token=token,
+        card_ids=card_ids,
+        workers=workers,
+        timeout=timeout,
+        reporter=reporter,
+        execution_context=execution_context,
+        cache_policy=cache_policy,
+        path_for_card=lambda card_id: f"/cards/{card_id}/comments",
+        page_size=page_size,
+        max_pages=max_pages,
+        result_field="comments",
+        transform_items=lambda items: _shape_nested_items(items, compact=compact, fields=fields),
+        worker_label="batch-comments",
+    )

kaiten_cli/runtime/support/restrictions.py

@@ -0,0 +1,62 @@
+"""Validation and selection for the undocumented restrictions API extension."""
+
+from __future__ import annotations
+
+from typing import Any
+from uuid import UUID
+
+from kaiten_cli.errors import ApiError, TransportError, ValidationError
+from kaiten_cli.i18n import tr
+
+
+def validate_restriction_payload(tool, payload: dict[str, Any]) -> None:
+    if "restriction_id" in payload:
+        try:
+            identifier = UUID(payload["restriction_id"])
+            if payload["restriction_id"].lower() not in (str(identifier), identifier.hex):
+                raise ValueError("Unsupported UUID spelling")
+        except ValueError as exc:
+            raise ValidationError(tr("Restriction ID must be a UUID.")) from exc
+    if tool.canonical_name == "restrictions.update" and not any(
+        key in payload for key in ("name", "conditions", "restrictions", "status")
+    ):
+        raise ValidationError(
+            tr(
+                "Restriction update requires name, conditions, restrictions or status; error_text alone is not accepted."
+            )
+        )
+
+
+def select_restriction(data: Any, restriction_id: str) -> dict[str, Any]:
+    if not isinstance(data, list):
+        raise TransportError(
+            tr("Restriction list response must be an array of objects with UUID identifiers.")
+        )
+    target_id = UUID(restriction_id)
+    selected = None
+    for item in data:
+        if not isinstance(item, dict) or not isinstance(item.get("id"), str):
+            raise TransportError(
+                tr("Restriction list response must be an array of objects with UUID identifiers.")
+            )
+        try:
+            item_id = UUID(item["id"])
+        except ValueError as exc:
+            raise TransportError(
+                tr("Restriction list response must be an array of objects with UUID identifiers.")
+            ) from exc
+        if (
+            item_id == target_id
+            and item.get("type") != "on_workflow"
+            and item.get("status") != "removed"
+        ):
+            selected = item
+    if selected is None:
+        raise ApiError(
+            404,
+            tr(
+                "Restriction {restriction_id} was not found in this space.",
+                restriction_id=restriction_id,
+            ),
+        )
+    return selected

kaiten_cli/runtime/support/spaces.py

@@ -0,0 +1,20 @@
+"""Support helpers for space-scoped aggregated reads."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+async def fetch_space_topology(client, space_id: int, *, timeout: float) -> dict[str, Any]:
+    boards = await client.get(f"/spaces/{space_id}/boards", timeout=timeout)
+    topology_boards: list[dict[str, Any]] = []
+    for board in boards if isinstance(boards, list) else []:
+        if not isinstance(board, dict) or "id" not in board:
+            continue
+        detail = await client.get(f"/boards/{board['id']}", timeout=timeout)
+        if not isinstance(detail, dict):
+            continue
+        detail.setdefault("columns", [])
+        detail.setdefault("lanes", [])
+        topology_boards.append(detail)
+    return {"space_id": space_id, "boards": topology_boards}

kaiten_cli/runtime/support/time_logs.py

@@ -0,0 +1,61 @@
+"""Support helpers for batch time-log reads."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from kaiten_cli.runtime.support.batch import DEFAULT_BATCH_WORKERS, fetch_card_collection_batch
+from kaiten_cli.runtime.support.pagination import (
+    API_MAX_PAGE_SIZE,
+    DEFAULT_COLLECTION_MAX_PAGES,
+)
+from kaiten_cli.runtime.transforms import compact_response, select_fields
+
+
+def _shape_time_log_items(items: list[Any], *, compact: bool, fields: str | None) -> list[Any]:
+    shaped = compact_response(items, compact)
+    return select_fields(shaped, fields)
+
+
+async def fetch_time_logs_batch(
+    *,
+    domain: str,
+    token: str,
+    card_ids: list[int],
+    workers: int = DEFAULT_BATCH_WORKERS,
+    page_size: int = API_MAX_PAGE_SIZE,
+    max_pages: int = DEFAULT_COLLECTION_MAX_PAGES,
+    for_date: str | None = None,
+    personal: bool | None = None,
+    compact: bool = False,
+    fields: str | None = None,
+    timeout: float,
+    reporter,
+    execution_context=None,
+    cache_policy: str = "request_scope",
+) -> dict[str, Any]:
+    def query_for_card(card_id: int) -> dict[str, Any] | None:
+        params: dict[str, Any] = {}
+        if for_date:
+            params["for_date"] = for_date
+        if personal is not None:
+            params["personal"] = personal
+        return params or None
+
+    return await fetch_card_collection_batch(
+        domain=domain,
+        token=token,
+        card_ids=card_ids,
+        workers=workers,
+        timeout=timeout,
+        reporter=reporter,
+        execution_context=execution_context,
+        cache_policy=cache_policy,
+        path_for_card=lambda card_id: f"/cards/{card_id}/time-logs",
+        query_for_card=query_for_card,
+        page_size=page_size,
+        max_pages=max_pages,
+        result_field="time_logs",
+        transform_items=lambda items: _shape_time_log_items(items, compact=compact, fields=fields),
+        worker_label="batch-time-logs",
+    )

kaiten_cli/runtime/support/tree.py

@@ -0,0 +1,140 @@
+"""Helpers for entity tree commands."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from kaiten_cli.errors import ConfigError
+from kaiten_cli.i18n import tr
+from kaiten_cli.runtime.support.pagination import fetch_all_offset_pages
+
+TREE_PAGE_LIMIT = 100
+TREE_MAX_PAGES = 200
+
+
+def sort_entities(entities: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    type_order = {"document_group": 0, "space": 1, "document": 2}
+    return sorted(
+        entities, key=lambda entity: (type_order.get(entity["type"], 99), entity.get("title", ""))
+    )
+
+
+def strip_id_none(entity: dict[str, Any]) -> dict[str, Any]:
+    return {key: value for key, value in entity.items() if not (key == "id" and value is None)}
+
+
+async def fetch_paginated_entities(
+    client,
+    path: str,
+    *,
+    timeout: float,
+    limit: int = TREE_PAGE_LIMIT,
+    max_pages: int = TREE_MAX_PAGES,
+    reporter=None,
+) -> list[dict[str, Any]]:
+    rows = await fetch_all_offset_pages(
+        client,
+        path,
+        timeout=timeout,
+        page_size=limit,
+        max_pages=max_pages,
+        reporter=reporter,
+    )
+    return [row for row in rows if isinstance(row, dict)]
+
+
+async def fetch_all_entities(client, *, timeout: float, reporter=None) -> list[dict[str, Any]]:
+    spaces_resp = await fetch_paginated_entities(
+        client, "/spaces", timeout=timeout, reporter=reporter
+    )
+    docs_resp = await fetch_paginated_entities(
+        client, "/documents", timeout=timeout, reporter=reporter
+    )
+    groups_resp = await fetch_paginated_entities(
+        client, "/document-groups", timeout=timeout, reporter=reporter
+    )
+
+    entities: list[dict[str, Any]] = []
+
+    for space in spaces_resp if isinstance(spaces_resp, list) else []:
+        uid = space.get("uid")
+        if uid is None:
+            continue
+        entities.append(
+            {
+                "type": "space",
+                "uid": uid,
+                "id": space.get("id"),
+                "title": space.get("title", ""),
+                "parent_entity_uid": space.get("parent_entity_uid"),
+            }
+        )
+
+    for document in docs_resp if isinstance(docs_resp, list) else []:
+        entities.append(
+            {
+                "type": "document",
+                "uid": document.get("uid", ""),
+                "id": None,
+                "title": document.get("title", ""),
+                "parent_entity_uid": document.get("parent_entity_uid"),
+            }
+        )
+
+    for group in groups_resp if isinstance(groups_resp, list) else []:
+        entities.append(
+            {
+                "type": "document_group",
+                "uid": group.get("uid", ""),
+                "id": None,
+                "title": group.get("title", ""),
+                "parent_entity_uid": group.get("parent_entity_uid"),
+            }
+        )
+
+    return entities
+
+
+def list_children(entities: list[dict[str, Any]], parent_uid: str | None) -> list[dict[str, Any]]:
+    if parent_uid is None:
+        known_uids = {entity.get("uid") for entity in entities}
+        children = [
+            entity for entity in entities if effective_parent_uid(entity, known_uids) is None
+        ]
+    else:
+        children = [entity for entity in entities if entity.get("parent_entity_uid") == parent_uid]
+    return [strip_id_none(entity) for entity in sort_entities(children)]
+
+
+def effective_parent_uid(entity: dict[str, Any], known_uids: set[Any]) -> Any:
+    parent_uid = entity.get("parent_entity_uid")
+    if parent_uid is not None and parent_uid not in known_uids:
+        return None
+    return parent_uid
+
+
+def build_tree(
+    entities: list[dict[str, Any]], root_uid: str | None, max_depth: int
+) -> list[dict[str, Any]]:
+    if root_uid is not None and not any(entity["uid"] == root_uid for entity in entities):
+        raise ConfigError(tr("Entity with uid '{value_0}' not found", value_0=root_uid))
+
+    known_uids = {entity.get("uid") for entity in entities}
+    by_parent: dict[str | None, list[dict[str, Any]]] = {}
+    for entity in entities:
+        by_parent.setdefault(effective_parent_uid(entity, known_uids), []).append(entity)
+
+    def recurse(parent_uid: str | None, depth: int) -> list[dict[str, Any]]:
+        children = sort_entities(by_parent.get(parent_uid, []))
+        result = []
+        for child in children:
+            node = strip_id_none(child)
+            node.pop("parent_entity_uid", None)
+            if max_depth == 0 or depth < max_depth:
+                node["children"] = recurse(child["uid"], depth + 1)
+            else:
+                node["children"] = []
+            result.append(node)
+        return result
+
+    return recurse(root_uid, 0)