azwork 0.1.0__py3-none-any.whl

azwork/__init__.py

@@ -0,0 +1,3 @@
+"""azwork — Azure DevOps Work Items TUI."""
+
+__version__ = "0.1.0"

azwork/__main__.py

@@ -0,0 +1,84 @@
+"""CLI entry point for azwork."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from azwork.config import Config, CONFIG_PATH
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="azwork",
+        description="TUI for triaging Azure DevOps work items",
+    )
+    parser.add_argument("--org", help="Azure DevOps organization")
+    parser.add_argument("--project", help="Azure DevOps project")
+    parser.add_argument("--output-dir", help="Default output directory for exports")
+    parser.add_argument("--setup", action="store_true", help="Run setup wizard")
+
+    args = parser.parse_args()
+
+    if args.setup:
+        _run_setup()
+        return
+
+    config = Config.load(
+        cli_org=args.org,
+        cli_project=args.project,
+        cli_output_dir=args.output_dir,
+    )
+
+    # If no config exists and no CLI args, run setup
+    if not config.org or not config.project:
+        if not CONFIG_PATH.exists():
+            print("No configuration found. Running setup wizard...")
+            _run_setup()
+            config = Config.load(
+                cli_org=args.org,
+                cli_project=args.project,
+                cli_output_dir=args.output_dir,
+            )
+        else:
+            errors = config.validate()
+            for err in errors:
+                print(f"Error: {err}", file=sys.stderr)
+            sys.exit(1)
+
+    errors = config.validate()
+    if errors:
+        for err in errors:
+            print(f"Error: {err}", file=sys.stderr)
+        sys.exit(1)
+
+    from azwork.tui.app import AzworkApp
+
+    app = AzworkApp(config)
+    app.run()
+
+
+def _run_setup() -> None:
+    """Interactive setup wizard to create ~/.azwork.yml."""
+    print("=== azwork Setup ===\n")
+
+    org = input("Azure DevOps Organization: ").strip()
+    project = input("Project name: ").strip()
+    output_dir = input("Default export directory [./bugs]: ").strip() or "./bugs"
+    types_input = input("Work item types (comma-separated) [Bug,Task,User Story]: ").strip()
+    types = [t.strip() for t in types_input.split(",")] if types_input else ["Bug", "Task", "User Story"]
+
+    config = Config(
+        org=org,
+        project=project,
+        default_output_dir=output_dir,
+        work_item_types=types,
+    )
+    config.save_default()
+    print(f"\nConfiguration saved to {CONFIG_PATH}")
+    print("Set AZURE_DEVOPS_PAT environment variable with your Personal Access Token.")
+    print("Run 'azwork' to start.")
+
+
+if __name__ == "__main__":
+    main()

azwork/api/client.py

@@ -0,0 +1,215 @@
+"""Azure DevOps REST API client."""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+import requests
+
+from azwork.api.models import Comment, WorkItem
+
+
+API_VERSION = "7.0"
+COMMENTS_API_VERSION = "7.0-preview.4"
+BATCH_SIZE = 200
+MAX_RETRIES = 3
+RETRY_BACKOFF = 1.0
+
+
+class AzureDevOpsError(Exception):
+    """Base error for API calls."""
+
+
+class AuthenticationError(AzureDevOpsError):
+    """PAT is invalid or missing required scope."""
+
+
+class NotFoundError(AzureDevOpsError):
+    """Organization or project not found."""
+
+
+class RateLimitError(AzureDevOpsError):
+    """Rate limit exceeded."""
+
+
+class AzureDevOpsClient:
+    """Client for Azure DevOps REST APIs."""
+
+    def __init__(self, org: str, project: str, pat: str) -> None:
+        self.org = org
+        self.project = project
+        self.base_url = f"https://dev.azure.com/{org}"
+        self.session = requests.Session()
+        self.session.auth = ("", pat)
+        self.session.headers["Content-Type"] = "application/json"
+        # In-memory cache for work items
+        self._cache: dict[int, WorkItem] = {}
+
+    def _request(
+        self,
+        method: str,
+        url: str,
+        json: dict | None = None,
+        params: dict | None = None,
+    ) -> dict:
+        """Make an API request with retry logic."""
+        for attempt in range(MAX_RETRIES):
+            try:
+                resp = self.session.request(method, url, json=json, params=params, timeout=30)
+            except requests.ConnectionError:
+                raise AzureDevOpsError(
+                    "Unable to connect to Azure DevOps. Check your network connection."
+                )
+            except requests.Timeout:
+                raise AzureDevOpsError("Request timed out. Please try again.")
+
+            if resp.status_code == 200:
+                return resp.json()
+            if resp.status_code == 401:
+                raise AuthenticationError(
+                    "Authentication failed (401). Verify your AZURE_DEVOPS_PAT "
+                    "and ensure it has 'Work Items → Read' scope."
+                )
+            if resp.status_code == 404:
+                raise NotFoundError(
+                    f"Not found (404). Verify org='{self.org}' and project='{self.project}' are correct."
+                )
+            if resp.status_code == 429:
+                if attempt < MAX_RETRIES - 1:
+                    wait = RETRY_BACKOFF * (2 ** attempt)
+                    time.sleep(wait)
+                    continue
+                raise RateLimitError("Rate limit exceeded. Please wait and try again.")
+            if resp.status_code >= 500:
+                if attempt < MAX_RETRIES - 1:
+                    time.sleep(RETRY_BACKOFF)
+                    continue
+                raise AzureDevOpsError(f"Server error ({resp.status_code}). Please try again later.")
+
+            raise AzureDevOpsError(f"API error {resp.status_code}: {resp.text[:200]}")
+
+        raise AzureDevOpsError("Max retries exceeded.")
+
+    def query_work_item_ids(self, wiql: str) -> list[int]:
+        """Execute a WIQL query and return work item IDs."""
+        url = f"{self.base_url}/{self.project}/_apis/wit/wiql"
+        params = {"api-version": API_VERSION}
+        data = self._request("POST", url, json={"query": wiql}, params=params)
+        return [item["id"] for item in data.get("workItems", [])]
+
+    def get_work_items(
+        self,
+        ids: list[int],
+        progress_callback: Any | None = None,
+    ) -> list[WorkItem]:
+        """Fetch work items by ID in batches. Returns cached items when available."""
+        if not ids:
+            return []
+
+        # Separate cached vs uncached
+        result: dict[int, WorkItem] = {}
+        to_fetch: list[int] = []
+        for wid in ids:
+            if wid in self._cache:
+                result[wid] = self._cache[wid]
+            else:
+                to_fetch.append(wid)
+
+        # Fetch uncached in batches
+        total_batches = (len(to_fetch) + BATCH_SIZE - 1) // BATCH_SIZE
+        for batch_idx in range(total_batches):
+            start = batch_idx * BATCH_SIZE
+            batch_ids = to_fetch[start : start + BATCH_SIZE]
+            ids_csv = ",".join(str(i) for i in batch_ids)
+
+            url = f"{self.base_url}/_apis/wit/workitems"
+            params = {
+                "ids": ids_csv,
+                "$expand": "all",
+                "api-version": API_VERSION,
+            }
+            data = self._request("GET", url, params=params)
+
+            for item_data in data.get("value", []):
+                item = WorkItem.from_api(item_data)
+                self._cache[item.id] = item
+                result[item.id] = item
+
+            if progress_callback:
+                progress_callback(batch_idx + 1, total_batches)
+
+        # Return in the original order
+        return [result[wid] for wid in ids if wid in result]
+
+    def get_comments(self, work_item_id: int) -> list[Comment]:
+        """Fetch comments for a work item."""
+        url = f"{self.base_url}/{self.project}/_apis/wit/workitems/{work_item_id}/comments"
+        params = {"api-version": COMMENTS_API_VERSION}
+        data = self._request("GET", url, params=params)
+        return [Comment.from_api(c) for c in data.get("comments", [])]
+
+    def get_fields(self) -> list[dict]:
+        """Fetch all available fields for the project."""
+        url = f"{self.base_url}/{self.project}/_apis/wit/fields"
+        params = {"api-version": API_VERSION}
+        data = self._request("GET", url, params=params)
+        return data.get("value", [])
+
+    def get_iterations(self) -> list[str]:
+        """Fetch iteration paths for the project."""
+        url = (
+            f"{self.base_url}/{self.project}/_apis/wit/classificationnodes/iterations"
+        )
+        params = {"api-version": API_VERSION, "$depth": 10}
+        try:
+            data = self._request("GET", url, params=params)
+            return _extract_paths(data, [])
+        except AzureDevOpsError:
+            return []
+
+    def get_work_item_url(self, work_item_id: int) -> str:
+        """Get the browser URL for a work item."""
+        return f"https://dev.azure.com/{self.org}/{self.project}/_workitems/edit/{work_item_id}"
+
+    def download_image(self, url: str) -> bytes:
+        """Download an image from an authenticated Azure DevOps URL."""
+        for attempt in range(MAX_RETRIES):
+            try:
+                resp = self.session.get(url, timeout=30)
+            except requests.ConnectionError:
+                raise AzureDevOpsError("Unable to connect to download image.")
+            except requests.Timeout:
+                raise AzureDevOpsError("Image download timed out.")
+
+            if resp.status_code == 200:
+                return resp.content
+            if resp.status_code == 401:
+                raise AuthenticationError("Authentication failed downloading image.")
+            if resp.status_code == 429:
+                if attempt < MAX_RETRIES - 1:
+                    time.sleep(RETRY_BACKOFF * (2 ** attempt))
+                    continue
+                raise RateLimitError("Rate limit exceeded downloading image.")
+            if resp.status_code >= 500 and attempt < MAX_RETRIES - 1:
+                time.sleep(RETRY_BACKOFF)
+                continue
+
+            raise AzureDevOpsError(f"Failed to download image ({resp.status_code}).")
+
+        raise AzureDevOpsError("Max retries exceeded downloading image.")
+
+    def clear_cache(self) -> None:
+        """Clear the work item cache."""
+        self._cache.clear()
+
+
+def _extract_paths(node: dict, parts: list[str]) -> list[str]:
+    """Recursively extract iteration paths from classification node tree."""
+    name = node.get("name", "")
+    current_parts = [*parts, name] if name else parts
+    path = "\\".join(current_parts)
+    paths = [path] if path else []
+    for child in node.get("children", []):
+        paths.extend(_extract_paths(child, current_parts))
+    return paths

azwork/api/models.py

@@ -0,0 +1,182 @@
+"""Data models for Azure DevOps work items."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+
+
+@dataclass
+class Comment:
+    id: int
+    text: str
+    author: str
+    created_date: str
+
+    @classmethod
+    def from_api(cls, data: dict) -> Comment:
+        author = data.get("createdBy", {}).get("displayName", "Unknown")
+        return cls(
+            id=data.get("id", 0),
+            text=data.get("text", ""),
+            author=author,
+            created_date=data.get("createdDate", ""),
+        )
+
+
+@dataclass
+class Relation:
+    rel_type: str
+    url: str
+    target_id: int | None = None
+    title: str | None = None
+
+    @classmethod
+    def from_api(cls, data: dict) -> Relation:
+        url = data.get("url", "")
+        # Extract work item ID from URL
+        target_id = None
+        if "/workItems/" in url:
+            try:
+                target_id = int(url.rsplit("/", 1)[-1])
+            except ValueError:
+                pass
+        attributes = data.get("attributes", {})
+        return cls(
+            rel_type=attributes.get("name", data.get("rel", "")),
+            url=url,
+            target_id=target_id,
+            title=None,
+        )
+
+
+@dataclass
+class WorkItem:
+    id: int
+    title: str = ""
+    work_item_type: str = ""
+    state: str = ""
+    area_path: str = ""
+    iteration_path: str = ""
+    assigned_to: str = ""
+    created_date: str = ""
+    changed_date: str = ""
+    tags: str = ""
+    priority: int | None = None
+    severity: str = ""
+    description: str = ""
+    repro_steps: str = ""
+    acceptance_criteria: str = ""
+    custom_fields: dict[str, str] = field(default_factory=dict)
+    relations: list[Relation] = field(default_factory=list)
+    comments: list[Comment] = field(default_factory=list)
+    url: str = ""
+
+    # Standard field reference names
+    STANDARD_FIELDS: set[str] = field(
+        default_factory=lambda: {
+            "System.Id",
+            "System.Title",
+            "System.Description",
+            "System.State",
+            "System.WorkItemType",
+            "System.AreaPath",
+            "System.IterationPath",
+            "System.AssignedTo",
+            "System.CreatedDate",
+            "System.ChangedDate",
+            "System.Tags",
+            "System.Reason",
+            "System.Rev",
+            "System.TeamProject",
+            "System.BoardColumn",
+            "System.BoardColumnDone",
+            "System.CommentCount",
+            "System.History",
+            "System.Watermark",
+            "System.AuthorizedAs",
+            "System.NodeName",
+            "System.RelatedLinkCount",
+            "System.ExternalLinkCount",
+            "System.HyperLinkCount",
+            "System.AttachedFileCount",
+            "System.AuthorizedDate",
+            "System.RevisedDate",
+            "System.PersonId",
+            "System.CreatedBy",
+            "System.ChangedBy",
+            "Microsoft.VSTS.Common.Priority",
+            "Microsoft.VSTS.Common.Severity",
+            "Microsoft.VSTS.Common.StateChangeDate",
+            "Microsoft.VSTS.Common.ActivatedDate",
+            "Microsoft.VSTS.Common.ActivatedBy",
+            "Microsoft.VSTS.Common.ResolvedDate",
+            "Microsoft.VSTS.Common.ResolvedBy",
+            "Microsoft.VSTS.Common.ResolvedReason",
+            "Microsoft.VSTS.Common.ClosedDate",
+            "Microsoft.VSTS.Common.ClosedBy",
+            "Microsoft.VSTS.Common.ValueArea",
+            "Microsoft.VSTS.Common.StackRank",
+            "Microsoft.VSTS.TCM.ReproSteps",
+            "Microsoft.VSTS.Common.AcceptanceCriteria",
+            "Microsoft.VSTS.Scheduling.StoryPoints",
+            "Microsoft.VSTS.Scheduling.Effort",
+            "Microsoft.VSTS.Scheduling.RemainingWork",
+            "Microsoft.VSTS.Scheduling.OriginalEstimate",
+            "Microsoft.VSTS.Scheduling.CompletedWork",
+            "WEF_",
+        },
+        repr=False,
+    )
+
+    @classmethod
+    def from_api(cls, data: dict) -> WorkItem:
+        fields = data.get("fields", {})
+        assigned_to = fields.get("System.AssignedTo", {})
+        if isinstance(assigned_to, dict):
+            assigned_to = assigned_to.get("displayName", "")
+
+        item = cls(
+            id=data.get("id", fields.get("System.Id", 0)),
+            title=fields.get("System.Title", ""),
+            work_item_type=fields.get("System.WorkItemType", ""),
+            state=fields.get("System.State", ""),
+            area_path=fields.get("System.AreaPath", ""),
+            iteration_path=fields.get("System.IterationPath", ""),
+            assigned_to=assigned_to,
+            created_date=_format_date(fields.get("System.CreatedDate", "")),
+            changed_date=_format_date(fields.get("System.ChangedDate", "")),
+            tags=fields.get("System.Tags", ""),
+            priority=fields.get("Microsoft.VSTS.Common.Priority"),
+            severity=fields.get("Microsoft.VSTS.Common.Severity", ""),
+            description=fields.get("System.Description", "") or "",
+            repro_steps=fields.get("Microsoft.VSTS.TCM.ReproSteps", "") or "",
+            acceptance_criteria=fields.get("Microsoft.VSTS.Common.AcceptanceCriteria", "") or "",
+            url=data.get("_links", {}).get("html", {}).get("href", ""),
+        )
+
+        # Extract custom fields
+        standard = item.STANDARD_FIELDS
+        for key, value in fields.items():
+            if value is None or value == "":
+                continue
+            is_standard = any(key.startswith(prefix) for prefix in ("System.", "Microsoft.VSTS."))
+            is_wef = key.startswith("WEF_")
+            if not is_standard and not is_wef:
+                item.custom_fields[key] = str(value)
+
+        # Extract relations
+        for rel_data in data.get("relations", []) or []:
+            item.relations.append(Relation.from_api(rel_data))
+
+        return item
+
+
+def _format_date(date_str: str) -> str:
+    if not date_str:
+        return ""
+    try:
+        dt = datetime.fromisoformat(date_str.replace("Z", "+00:00"))
+        return dt.strftime("%Y-%m-%d")
+    except (ValueError, TypeError):
+        return date_str

azwork/api/wiql.py

@@ -0,0 +1,61 @@
+"""WIQL query builder for Azure DevOps."""
+
+from __future__ import annotations
+
+
+def build_wiql(
+    project: str,
+    work_item_types: list[str] | None = None,
+    states: list[str] | None = None,
+    iteration_path: str | None = None,
+    area_path: str | None = None,
+    assigned_to: str | None = None,
+    title_contains: str | None = None,
+    order_by: str = "System.ChangedDate",
+    order_dir: str = "DESC",
+) -> str:
+    """Build a WIQL query string with optional filters."""
+    conditions: list[str] = [
+        f"[System.TeamProject] = '{_escape(project)}'"
+    ]
+
+    if work_item_types:
+        type_list = ", ".join(f"'{_escape(t)}'" for t in work_item_types)
+        conditions.append(f"[System.WorkItemType] IN ({type_list})")
+
+    if states:
+        state_list = ", ".join(f"'{_escape(s)}'" for s in states)
+        conditions.append(f"[System.State] IN ({state_list})")
+
+    if iteration_path:
+        conditions.append(
+            f"[System.IterationPath] UNDER '{_escape(iteration_path)}'"
+        )
+
+    if area_path:
+        conditions.append(
+            f"[System.AreaPath] UNDER '{_escape(area_path)}'"
+        )
+
+    if assigned_to:
+        conditions.append(
+            f"[System.AssignedTo] = '{_escape(assigned_to)}'"
+        )
+
+    if title_contains:
+        conditions.append(
+            f"[System.Title] CONTAINS '{_escape(title_contains)}'"
+        )
+
+    where_clause = " AND ".join(conditions)
+    query = (
+        f"SELECT [System.Id] FROM WorkItems "
+        f"WHERE {where_clause} "
+        f"ORDER BY [{order_by}] {order_dir}"
+    )
+    return query
+
+
+def _escape(value: str) -> str:
+    """Escape single quotes in WIQL values."""
+    return value.replace("'", "''")

azwork/config.py

@@ -0,0 +1,75 @@
+"""Configuration loading from ~/.azwork.yml and CLI args."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+
+
+CONFIG_PATH = Path.home() / ".azwork.yml"
+
+
+@dataclass
+class Config:
+    org: str = ""
+    project: str = ""
+    default_output_dir: str = "./bugs"
+    work_item_types: list[str] = field(default_factory=lambda: ["Bug", "Task", "User Story"])
+    pat: str = ""
+
+    @classmethod
+    def load(cls, cli_org: str | None = None, cli_project: str | None = None,
+             cli_output_dir: str | None = None) -> Config:
+        cfg = cls()
+
+        # Load from YAML if exists
+        if CONFIG_PATH.exists():
+            try:
+                with open(CONFIG_PATH) as f:
+                    data = yaml.safe_load(f) or {}
+                cfg.org = data.get("org", "")
+                cfg.project = data.get("project", "")
+                cfg.default_output_dir = data.get("default_output_dir", "./bugs")
+                cfg.work_item_types = data.get("work_item_types", cfg.work_item_types)
+            except Exception:
+                pass
+
+        # CLI overrides
+        if cli_org:
+            cfg.org = cli_org
+        if cli_project:
+            cfg.project = cli_project
+        if cli_output_dir:
+            cfg.default_output_dir = cli_output_dir
+
+        # PAT from environment
+        cfg.pat = os.environ.get("AZURE_DEVOPS_PAT", "")
+
+        return cfg
+
+    def save_default(self) -> None:
+        data = {
+            "org": self.org,
+            "project": self.project,
+            "default_output_dir": self.default_output_dir,
+            "work_item_types": self.work_item_types,
+        }
+        with open(CONFIG_PATH, "w") as f:
+            yaml.dump(data, f, default_flow_style=False)
+
+    def validate(self) -> list[str]:
+        errors = []
+        if not self.pat:
+            errors.append(
+                "AZURE_DEVOPS_PAT environment variable is not set.\n"
+                "Create a PAT at https://dev.azure.com/{org}/_usersSettings/tokens\n"
+                "Required scope: Work Items → Read"
+            )
+        if not self.org:
+            errors.append("Organization not set. Use --org or set 'org' in ~/.azwork.yml")
+        if not self.project:
+            errors.append("Project not set. Use --project or set 'project' in ~/.azwork.yml")
+        return errors