kd-cli 2.0.4__py3-none-any.whl

kd/__init__.py

@@ -0,0 +1,45 @@
+"""kd — knowledge dispatcher for live knowledge systems.
+
+SDK-first design: import YouTrackClient for programmatic access,
+or use the ``kd`` command for CLI operations.
+
+Usage::
+
+    from kd import YouTrackClient
+
+    client = YouTrackClient(url="https://example.youtrack.cloud", token="...")
+    projects = client.projects.list()
+"""
+
+from importlib.metadata import version as _pkg_version
+
+__version__ = _pkg_version("kd-cli")
+
+from kd.client import YouTrackClient
+from kd.config import ConfigSource, ResolvedConfig, resolve_config
+from kd.debug import DebugLevel, DebugLog
+from kd.exceptions import (
+    APIError,
+    AuthError,
+    ConfigError,
+    ConflictError,
+    NotFoundError,
+    ValidationError,
+    KdError,
+)
+
+__all__ = [
+    "APIError",
+    "AuthError",
+    "ConfigError",
+    "ConfigSource",
+    "ConflictError",
+    "DebugLevel",
+    "DebugLog",
+    "NotFoundError",
+    "ResolvedConfig",
+    "ValidationError",
+    "YouTrackClient",
+    "KdError",
+    "resolve_config",
+]

kd/api/__init__.py

@@ -0,0 +1,15 @@
+"""Low-level API wrappers.
+
+Four API layers, same bearer token:
+- ArticlesAPI: ``/api/articles`` — knowledge base articles
+- TagsAPI: ``/api/tags`` — tags, issue/article tagging
+- YouTrackAPI: ``/api/...`` — projects, issues, fields, time tracking
+- HubAPI: ``/hub/api/rest/...`` — users, groups, project teams, roles
+"""
+
+from kd.api.articles import ArticlesAPI
+from kd.api.hub import HubAPI
+from kd.api.tags import TagsAPI
+from kd.api.youtrack import YouTrackAPI
+
+__all__ = ["ArticlesAPI", "HubAPI", "TagsAPI", "YouTrackAPI"]

kd/api/articles.py

@@ -0,0 +1,232 @@
+"""Articles REST API wrapper.
+
+Covers ``/api/articles`` endpoints:
+- Articles: list (global + project-scoped), get, create, update, delete
+- Child articles: list, attach, detach parent
+- Comments: list, create
+- Attachments: list, get, create, delete
+
+Articles have no ``query`` parameter — filtering is project-scoped only.
+"""
+
+from __future__ import annotations
+
+from kd.api.http import HttpClient
+from kd.models import (
+    Article,
+    ArticleCreate,
+    ArticleUpdate,
+    Attachment,
+    Comment,
+    CommentCreate,
+    FieldSet,
+)
+
+# List fields omit content to keep responses lightweight
+_ARTICLE_LIST_FIELDS = str(
+    FieldSet(
+        "id",
+        "idReadable",
+        "summary",
+        "created",
+        "updated",
+        "hasChildren",
+        project=FieldSet("id", "name"),
+        reporter=FieldSet("id", "name"),
+        parentArticle=FieldSet("id", "idReadable"),
+    )
+)
+
+# Tag-scan fields include tags for client-side tag filtering.
+# Kept separate from _ARTICLE_LIST_FIELDS so normal article list
+# calls don't pay the tag payload cost.
+_ARTICLE_TAG_SCAN_FIELDS = str(
+    FieldSet(
+        "id",
+        "idReadable",
+        "summary",
+        "created",
+        "updated",
+        "hasChildren",
+        project=FieldSet("id", "name"),
+        reporter=FieldSet("id", "name"),
+        parentArticle=FieldSet("id", "idReadable"),
+        tags=FieldSet("id", "name"),
+    )
+)
+
+# Detail fields include content for single-article views
+_ARTICLE_DETAIL_FIELDS = str(
+    FieldSet(
+        "id",
+        "idReadable",
+        "summary",
+        "content",
+        "created",
+        "updated",
+        "hasChildren",
+        project=FieldSet("id", "name"),
+        reporter=FieldSet("id", "name"),
+        parentArticle=FieldSet("id", "idReadable"),
+        tags=FieldSet("id", "name"),
+    )
+)
+
+
+_ARTICLE_COMMENT_FIELDS = "id,text,pinned,author(id,login,name),created,updated"
+_ARTICLE_ATTACHMENT_FIELDS = (
+    "id,name,size,mimeType,extension,author(id,login,name),created,updated,url"
+)
+
+
+class ArticlesAPI:
+    """Articles REST API wrapper (/api/articles)."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    # --- List ---
+
+    def list_articles(self, top: int = 50, skip: int = 0) -> list[Article]:
+        data = self._http.get(
+            "/articles",
+            fields=_ARTICLE_LIST_FIELDS,
+            params={"$top": top, "$skip": skip},
+        )
+        return [Article.model_validate(a) for a in data]
+
+    def list_project_articles(self, project_id: str, top: int = 50, skip: int = 0) -> list[Article]:
+        data = self._http.get(
+            f"/admin/projects/{project_id}/articles",
+            fields=_ARTICLE_LIST_FIELDS,
+            params={"$top": top, "$skip": skip},
+        )
+        return [Article.model_validate(a) for a in data]
+
+    # --- Tag scan (articles with tags for client-side filtering) ---
+
+    def list_articles_with_tags(self, top: int = 50, skip: int = 0) -> list[Article]:
+        data = self._http.get(
+            "/articles",
+            fields=_ARTICLE_TAG_SCAN_FIELDS,
+            params={"$top": top, "$skip": skip},
+        )
+        return [Article.model_validate(a) for a in data]
+
+    def list_project_articles_with_tags(
+        self, project_id: str, top: int = 50, skip: int = 0
+    ) -> list[Article]:
+        data = self._http.get(
+            f"/admin/projects/{project_id}/articles",
+            fields=_ARTICLE_TAG_SCAN_FIELDS,
+            params={"$top": top, "$skip": skip},
+        )
+        return [Article.model_validate(a) for a in data]
+
+    # --- Get ---
+
+    def get_article(self, article_id: str) -> Article:
+        data = self._http.get(
+            f"/articles/{article_id}",
+            fields=_ARTICLE_DETAIL_FIELDS,
+        )
+        return Article.model_validate(data)
+
+    # --- Children ---
+
+    def list_child_articles(self, article_id: str, top: int = 50, skip: int = 0) -> list[Article]:
+        data = self._http.get(
+            f"/articles/{article_id}/childArticles",
+            fields=_ARTICLE_LIST_FIELDS,
+            params={"$top": top, "$skip": skip},
+        )
+        return [Article.model_validate(a) for a in data]
+
+    # --- Create / Update / Delete ---
+
+    def create_article(self, article: ArticleCreate) -> Article:
+        data = self._http.post(
+            "/articles",
+            json=article.model_dump(by_alias=True, exclude_none=True),
+            fields=_ARTICLE_DETAIL_FIELDS,
+        )
+        return Article.model_validate(data)
+
+    def update_article(self, article_id: str, update: ArticleUpdate) -> Article:
+        data = self._http.post(
+            f"/articles/{article_id}",
+            json=update.model_dump(by_alias=True, exclude_none=True),
+            fields=_ARTICLE_DETAIL_FIELDS,
+        )
+        return Article.model_validate(data)
+
+    def delete_article(self, article_id: str) -> None:
+        self._http.delete(f"/articles/{article_id}")
+
+    # --- Comments ---
+
+    def list_article_comments(self, article_id: str) -> list[Comment]:
+        data = self._http.get(
+            f"/articles/{article_id}/comments",
+            fields=_ARTICLE_COMMENT_FIELDS,
+        )
+        return [Comment.model_validate(c) for c in data]
+
+    def create_article_comment(self, article_id: str, comment: CommentCreate) -> Comment:
+        data = self._http.post(
+            f"/articles/{article_id}/comments",
+            json=comment.model_dump(exclude_none=True),
+            fields=_ARTICLE_COMMENT_FIELDS,
+        )
+        return Comment.model_validate(data)
+
+    # --- Attachments ---
+
+    def list_article_attachments(self, article_id: str) -> list[Attachment]:
+        data = self._http.get(
+            f"/articles/{article_id}/attachments",
+            fields=_ARTICLE_ATTACHMENT_FIELDS,
+        )
+        return [Attachment.model_validate(a) for a in data]
+
+    def get_article_attachment(self, article_id: str, attachment_id: str) -> Attachment:
+        data = self._http.get(
+            f"/articles/{article_id}/attachments/{attachment_id}",
+            fields=_ARTICLE_ATTACHMENT_FIELDS,
+        )
+        return Attachment.model_validate(data)
+
+    def create_article_attachment(
+        self, article_id: str, file_name: str, file_content: bytes
+    ) -> Attachment:
+        data = self._http.post_file(
+            f"/articles/{article_id}/attachments",
+            file_name=file_name,
+            file_content=file_content,
+            fields=_ARTICLE_ATTACHMENT_FIELDS,
+        )
+        if isinstance(data, list):
+            return Attachment.model_validate(data[0])
+        return Attachment.model_validate(data)
+
+    def delete_article_attachment(self, article_id: str, attachment_id: str) -> None:
+        self._http.delete(f"/articles/{article_id}/attachments/{attachment_id}")
+
+    # --- Hierarchy ---
+
+    def attach_child_article(self, parent_id: str, child_id: str) -> None:
+        """Attach an existing article as a child of another."""
+        self._http.post(
+            f"/articles/{parent_id}/childArticles",
+            json={"id": child_id},
+        )
+
+    def detach_parent_article(self, article_id: str) -> None:
+        """Remove an article's parent (move to project root).
+
+        Uses POST update with parentArticle set to null.
+        """
+        self._http.post(
+            f"/articles/{article_id}",
+            json={"parentArticle": None},
+        )

kd/api/http.py

@@ -0,0 +1,234 @@
+"""Shared HTTP client.
+
+Wraps httpx.Client with:
+- Bearer token authentication
+- Base URL management
+- Explicit ``fields`` parameter support (YouTrack requires this)
+- Error handling: maps HTTP errors to kd exceptions
+- Retry logic for transient failures
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from typing import Any
+
+import httpx
+
+from kd.debug import DebugLog
+from kd.exceptions import (
+    APIError,
+    AuthError,
+    ConflictError,
+    NotFoundError,
+    PermissionDeniedError,
+    enrich_error,
+)
+
+_RETRYABLE_STATUSES = {429, 502, 503}
+_MAX_RETRIES = 3
+
+
+class HttpClient:
+    """Low-level HTTP client with auth, retry, and error mapping."""
+
+    def __init__(
+        self,
+        base_url: str,
+        token: str,
+        timeout: float = 30.0,
+        debug_log: DebugLog | None = None,
+    ) -> None:
+        self._debug = debug_log or DebugLog()
+        self._client = httpx.Client(
+            base_url=base_url,
+            headers={
+                "Authorization": f"Bearer {token}",
+                "Accept": "application/json",
+            },
+            timeout=timeout,
+        )
+
+    def get(
+        self,
+        path: str,
+        fields: str | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> Any:
+        """GET with automatic fields injection."""
+        all_params: dict[str, Any] = dict(params or {})
+        if fields:
+            all_params["fields"] = fields
+        response = self._request("GET", path, params=all_params)
+        return response.json()
+
+    def post(
+        self,
+        path: str,
+        json: dict[str, Any] | None = None,
+        fields: str | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> Any:
+        """POST with optional fields on query string."""
+        all_params: dict[str, Any] = dict(params or {})
+        if fields:
+            all_params["fields"] = fields
+        response = self._request("POST", path, json=json, params=all_params or None)
+        if response.status_code == 204 or not response.content:
+            return {}
+        return response.json()
+
+    def post_file(
+        self,
+        path: str,
+        file_name: str,
+        file_content: bytes,
+        fields: str | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> Any:
+        """POST multipart file upload."""
+        all_params: dict[str, Any] = dict(params or {})
+        if fields:
+            all_params["fields"] = fields
+        response = self._request(
+            "POST",
+            path,
+            files={"file": (file_name, file_content)},
+            params=all_params or None,
+        )
+        if response.status_code == 204 or not response.content:
+            return {}
+        return response.json()
+
+    def get_bytes(
+        self,
+        path: str,
+        params: dict[str, Any] | None = None,
+    ) -> bytes:
+        """GET raw bytes (for file downloads)."""
+        response = self._request("GET", path, params=params)
+        return response.content
+
+    def delete(self, path: str) -> None:
+        """DELETE. Returns nothing."""
+        self._request("DELETE", path)
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> httpx.Response:
+        """Execute request with retry and error mapping."""
+        d = self._debug
+
+        # Log request details before first attempt
+        if params := kwargs.get("params"):
+            d.debug("http", f"{method} {path}")
+            d.debug("http", f"  params: {params}")
+        else:
+            d.debug("http", f"{method} {path}")
+
+        if kwargs.get("json") is not None:
+            d.trace("http", f"  body: {kwargs['json']}")
+        d.trace("http", "  headers: Authorization=Bearer ***")
+
+        start = time.monotonic()
+        last_response: httpx.Response | None = None
+        for attempt in range(_MAX_RETRIES):
+            try:
+                response = self._client.request(method, path, **kwargs)
+            except httpx.HTTPError as e:
+                d.info("http", f"{method} {path} -> connection error: {e}")
+                raise APIError(0, f"Connection error: {e}") from e
+
+            duration_ms = (time.monotonic() - start) * 1000
+
+            if response.status_code < 400:
+                d.info(
+                    "http",
+                    f"{method} {path} -> {response.status_code} ({duration_ms:.0f}ms)",
+                )
+                d.trace("http", f"  response: {response.text[:1000]}")
+                return response
+
+            last_response = response
+            if response.status_code in _RETRYABLE_STATUSES and attempt < _MAX_RETRIES - 1:
+                d.debug(
+                    "http",
+                    f"  retry {attempt + 1}/{_MAX_RETRIES} (status {response.status_code})",
+                )
+                continue
+
+            d.info(
+                "http",
+                f"{method} {path} -> {response.status_code} ({duration_ms:.0f}ms) FAILED",
+            )
+            d.trace("http", f"  response: {response.text[:1000]}")
+            self._raise_for_status(response)
+
+        # Satisfy type checker — _raise_for_status always raises
+        assert last_response is not None
+        self._raise_for_status(last_response)
+        raise AssertionError("unreachable")  # pragma: no cover
+
+    @staticmethod
+    def _extract_message(body: str) -> str:
+        """Extract a human-readable message from a YouTrack error response.
+
+        YouTrack returns structured JSON errors like::
+
+            {"error": "invalid_query",
+             "error_description": "Can't parse search query",
+             "error_children": [{"error": "detail message"}]}
+
+        This extracts the most specific message available, falling back
+        to the raw body for non-JSON responses.
+        """
+        try:
+            data = json.loads(body)
+        except (json.JSONDecodeError, TypeError):
+            return body
+
+        if not isinstance(data, dict):
+            return body
+
+        # Most specific: child error messages
+        children = data.get("error_children")
+        if isinstance(children, list) and children:
+            child_msgs = [c["error"] for c in children if isinstance(c, dict) and "error" in c]
+            if child_msgs:
+                return "; ".join(child_msgs)
+
+        # Next: error_description
+        desc = data.get("error_description")
+        if desc:
+            return str(desc)
+
+        # Fallback: error field (often a code like "invalid_query")
+        error = data.get("error")
+        if error:
+            return str(error)
+
+        return body
+
+    @staticmethod
+    def _raise_for_status(response: httpx.Response) -> None:
+        """Map HTTP status to kd exceptions. Always raises."""
+        body = response.text
+        status = response.status_code
+        extracted = HttpClient._extract_message(body)
+        request_path = response.request.url.path if response.request else None
+        message, suggestion = enrich_error(extracted, status=status, path=request_path)
+        if status == 401:
+            raise AuthError(f"Authentication failed: {message}")
+        if status == 403:
+            body_lower = body.lower()
+            if suggestion or "permission" in body_lower or "access" in body_lower:
+                raise PermissionDeniedError(message, body, suggestion)
+            raise APIError(403, f"Access denied: {message}", body, suggestion)
+        if status == 404:
+            raise NotFoundError(message, body, suggestion)
+        if status == 409:
+            raise ConflictError(message, body, suggestion)
+        raise APIError(status, f"API error ({status}): {message}", body, suggestion)
+
+    def close(self) -> None:
+        """Close the underlying httpx client."""
+        self._client.close()

kd/api/hub.py

@@ -0,0 +1,69 @@
+"""JetBrains Hub REST API wrapper.
+
+Covers ``/hub/api/rest/...`` endpoints:
+- Users: list, create, delete
+- Project teams: list, add member
+- Roles: list, assign to user for project
+
+Hub uses UUIDs for all entity IDs. The ringId field on YT entities
+bridges the two ID systems.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from kd.api.http import HttpClient
+from kd.models import ProjectTeam, User, UserCreate
+
+
+class HubAPI:
+    """JetBrains Hub REST API wrapper (/hub/api/rest/...)."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    # --- Users ---
+
+    def list_users(self, top: int = 100, skip: int = 0) -> list[User]:
+        data = self._http.get(
+            "/users",
+            fields="id,login,name,email,banned",
+            params={"$top": top, "$skip": skip},
+        )
+        users = data.get("users", data) if isinstance(data, dict) else data
+        return [User.model_validate(u) for u in users]
+
+    def create_user(self, user: UserCreate) -> User:
+        data = self._http.post("/users", json=user.model_dump(exclude_none=True))
+        return User.model_validate(data)
+
+    def delete_user(self, hub_user_id: str) -> None:
+        self._http.delete(f"/users/{hub_user_id}")
+
+    # --- Project Teams ---
+
+    def list_project_teams(self, top: int = 100, skip: int = 0) -> list[ProjectTeam]:
+        data = self._http.get(
+            "/projectteams",
+            fields="id,name,project(id,name)",
+            params={"$top": top, "$skip": skip},
+        )
+        teams = data.get("projectteams", data) if isinstance(data, dict) else data
+        return [ProjectTeam.model_validate(t) for t in teams]
+
+    def add_team_member(self, team_id: str, user_hub_id: str) -> None:
+        self._http.post(f"/projectteams/{team_id}/users", json={"id": user_hub_id})
+
+    # --- Roles ---
+
+    def list_roles(self) -> list[dict[str, Any]]:
+        data = self._http.get("/roles", fields="id,name,key", params={"$top": 50})
+        roles: list[dict[str, Any]] = data.get("roles", data) if isinstance(data, dict) else data
+        return roles
+
+    def assign_role(self, hub_user_id: str, role_id: str, project_ring_id: str) -> None:
+        self._http.post(
+            f"/users/{hub_user_id}/projectroles",
+            json={"role": {"id": role_id}, "project": {"id": project_ring_id}},
+        )

kd/api/saved_queries.py

@@ -0,0 +1,76 @@
+"""Saved queries REST API wrapper.
+
+Covers ``/api/savedQueries`` CRUD plus the user-scoped listing at
+``/api/users/{userID}/savedQueries``. Sharing settings
+(``readSharingSettings`` / ``updateSharingSettings``) are deliberately
+excluded from the default field set; M022 ships personal CRUD only and a
+future milestone can layer permissions on top.
+"""
+
+from __future__ import annotations
+
+from kd.api.http import HttpClient
+from kd.models import FieldSet, SavedQuery, SavedQueryCreate, SavedQueryUpdate
+
+_SAVED_QUERY_FIELDS = str(
+    FieldSet(
+        "id",
+        "name",
+        "query",
+        owner=FieldSet("id", "name"),
+    )
+)
+
+
+class SavedQueriesAPI:
+    """Saved queries REST API wrapper (/api/savedQueries, /api/users/*/savedQueries)."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def list_saved_queries(self, top: int = 50, skip: int = 0) -> list[SavedQuery]:
+        data = self._http.get(
+            "/savedQueries",
+            fields=_SAVED_QUERY_FIELDS,
+            params={"$top": top, "$skip": skip},
+        )
+        return [SavedQuery.model_validate(sq) for sq in data]
+
+    def get_saved_query(self, sq_id: str) -> SavedQuery:
+        data = self._http.get(f"/savedQueries/{sq_id}", fields=_SAVED_QUERY_FIELDS)
+        return SavedQuery.model_validate(data)
+
+    def create_saved_query(self, sq: SavedQueryCreate) -> SavedQuery:
+        data = self._http.post(
+            "/savedQueries",
+            json=sq.model_dump(by_alias=True),
+            fields=_SAVED_QUERY_FIELDS,
+        )
+        return SavedQuery.model_validate(data)
+
+    def update_saved_query(self, sq_id: str, update: SavedQueryUpdate) -> SavedQuery:
+        data = self._http.post(
+            f"/savedQueries/{sq_id}",
+            json=update.model_dump(by_alias=True, exclude_none=True),
+            fields=_SAVED_QUERY_FIELDS,
+        )
+        return SavedQuery.model_validate(data)
+
+    def delete_saved_query(self, sq_id: str) -> None:
+        self._http.delete(f"/savedQueries/{sq_id}")
+
+    def list_user_saved_queries(
+        self, user_id: str, top: int = 50, skip: int = 0
+    ) -> list[SavedQuery]:
+        """List saved queries owned by a specific user.
+
+        The literal string ``"me"`` is accepted as ``user_id`` and resolves
+        to the authenticated user server-side (verified against
+        ``vod.youtrack.cloud``).
+        """
+        data = self._http.get(
+            f"/users/{user_id}/savedQueries",
+            fields=_SAVED_QUERY_FIELDS,
+            params={"$top": top, "$skip": skip},
+        )
+        return [SavedQuery.model_validate(sq) for sq in data]