azwork 0.1.0__tar.gz

azwork-0.1.0/PKG-INFO

@@ -0,0 +1,259 @@
+Metadata-Version: 2.4
+Name: azwork
+Version: 0.1.0
+Summary: TUI tool for triaging Azure DevOps work items
+Author: Antonio Pastorino
+License: MIT
+Project-URL: Homepage, https://github.com/a-pastorino/azwork
+Project-URL: Repository, https://github.com/a-pastorino/azwork
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Software Development :: Bug Tracking
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: textual>=0.47.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: beautifulsoup4>=4.12.0
+Requires-Dist: pyperclip>=1.8.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+
+# azwork
+
+A terminal UI for triaging Azure DevOps work items. Browse, inspect, and export work items as Markdown — optimized for use as context in Claude Code sessions.
+
+![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+## Features
+
+- **Interactive TUI** — browse work items in a filterable, sortable table
+- **Detail view** — inspect description, repro steps, comments, relations, and custom fields
+- **Markdown export** — export any work item to a clean `.md` file
+- **Claude Code prompt export** — generate a ready-to-use prompt wrapping the work item
+- **Clipboard support** — copy Markdown to clipboard with a single keystroke
+- **Smart caching** — fetched work items are cached in memory to keep navigation fast
+- **HTML → Markdown** — Azure DevOps HTML content is automatically converted
+
+## Installation
+
+```bash
+pip install azwork
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/a-pastorino/azwork.git
+cd azwork
+pip install .
+```
+
+For development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick start
+
+### 1. Create a Personal Access Token
+
+Go to `https://dev.azure.com/{your-org}/_usersSettings/tokens` and create a token with the **Work Items → Read** scope.
+
+Export it as an environment variable:
+
+```bash
+export AZURE_DEVOPS_PAT="your-token-here"
+```
+
+### 2. Run the setup wizard
+
+```bash
+azwork --setup
+```
+
+This creates `~/.azwork.yml` interactively.
+
+### 3. Launch
+
+```bash
+azwork
+```
+
+## Usage
+
+```bash
+# Use defaults from ~/.azwork.yml
+azwork
+
+# Override org and project
+azwork --org myorg --project myproject
+
+# Custom export directory
+azwork --output-dir ./sprint-bugs
+
+# Re-run setup
+azwork --setup
+```
+
+## Configuration
+
+azwork reads its configuration from `~/.azwork.yml`. CLI arguments always take priority.
+
+### `~/.azwork.yml` anatomy
+
+```yaml
+# Azure DevOps organization name (the {org} part of dev.azure.com/{org})
+org: myorg
+
+# Project name within the organization
+project: myproject
+
+# Default directory where exported Markdown files are saved.
+# Can be an absolute path or relative to where you run azwork.
+# Created automatically on first export if it doesn't exist.
+default_output_dir: ./bugs
+
+# Work item types to include in queries.
+# These are used both as WIQL filter and as options in the Type dropdown.
+# Common values: Bug, Task, User Story, Epic, Feature, Issue, Test Case
+work_item_types:
+  - Bug
+  - Task
+  - User Story
+```
+
+All fields are optional when using CLI overrides. The PAT is **never** stored in the config file — it is always read from the `AZURE_DEVOPS_PAT` environment variable.
+
+### Minimal example
+
+```yaml
+org: contoso
+project: webapp
+```
+
+### Full example
+
+```yaml
+org: contoso
+project: webapp
+default_output_dir: ~/work/bugs
+work_item_types:
+  - Bug
+  - Task
+  - User Story
+  - Feature
+  - Epic
+```
+
+## Keybindings
+
+### List screen
+
+| Key | Action |
+|-----|--------|
+| `↑` `↓` | Navigate rows |
+| `Enter` | Open detail view |
+| `E` | Export highlighted item to Markdown |
+| `R` | Refresh (re-fetch from API) |
+| `Q` | Quit |
+| `?` | Show help |
+
+Column headers are clickable to sort by that column.
+
+### Detail screen
+
+| Key | Action |
+|-----|--------|
+| `Esc` | Back to list |
+| `E` | Export as Markdown |
+| `P` | Export as Claude Code prompt |
+| `C` | Copy Markdown to clipboard |
+| `O` | Open in browser |
+| `?` | Show help |
+
+## Export formats
+
+### Markdown
+
+A structured Markdown file with metadata table, description, repro steps, acceptance criteria, discussion thread, related items, and custom fields.
+
+```
+bugs/1234-login-fails-special-chars.md
+```
+
+### Claude Code prompt
+
+Same Markdown content wrapped in a prompt template that instructs Claude Code to analyze and resolve the work item:
+
+```markdown
+# Task: Resolve the following work item
+
+Analyze the work item described below and take the necessary actions to resolve it.
+The project context is described in the CLAUDE.md file at the repository root.
+
+## Work Item
+[... full work item markdown ...]
+
+## Instructions
+1. Analyze the work item and identify the affected files
+2. Implement the fix or the requested feature
+3. Write or update tests to cover the case
+4. Verify that existing tests are not broken
+5. Briefly describe the changes you made
+```
+
+## Project structure
+
+```
+azwork/
+├── __main__.py              # CLI entry point (argparse)
+├── config.py                # YAML config loading + CLI merge
+├── utils.py                 # HTML→Markdown conversion
+├── api/
+│   ├── client.py            # Azure DevOps REST client (auth, batching, cache)
+│   ├── wiql.py              # WIQL query builder
+│   └── models.py            # WorkItem, Comment, Relation dataclasses
+├── tui/
+│   ├── app.py               # Textual App
+│   ├── screens/
+│   │   ├── list_screen.py   # Work item list with filters
+│   │   └── detail_screen.py # Single item detail + export dialog
+│   └── widgets/
+│       ├── filter_bar.py    # Type / State / Iteration / Search filters
+│       └── item_table.py    # Sortable DataTable for work items
+└── export/
+    ├── markdown.py          # Markdown generation
+    └── prompt.py            # Claude Code prompt wrapper
+```
+
+## Running tests
+
+```bash
+pytest
+```
+
+Tests mock all API calls and cover:
+
+- API client (pagination, HTTP errors, caching, response parsing)
+- WIQL query construction with various filter combinations
+- Markdown export (formatting, edge cases, empty fields)
+- HTML → Markdown conversion (all supported tags)
+
+## Requirements
+
+- Python 3.10+
+- An Azure DevOps organization with work items
+- A PAT with **Work Items → Read** scope
+
+## License
+
+MIT

azwork-0.1.0/README.md

@@ -0,0 +1,232 @@
+# azwork
+
+A terminal UI for triaging Azure DevOps work items. Browse, inspect, and export work items as Markdown — optimized for use as context in Claude Code sessions.
+
+![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+## Features
+
+- **Interactive TUI** — browse work items in a filterable, sortable table
+- **Detail view** — inspect description, repro steps, comments, relations, and custom fields
+- **Markdown export** — export any work item to a clean `.md` file
+- **Claude Code prompt export** — generate a ready-to-use prompt wrapping the work item
+- **Clipboard support** — copy Markdown to clipboard with a single keystroke
+- **Smart caching** — fetched work items are cached in memory to keep navigation fast
+- **HTML → Markdown** — Azure DevOps HTML content is automatically converted
+
+## Installation
+
+```bash
+pip install azwork
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/a-pastorino/azwork.git
+cd azwork
+pip install .
+```
+
+For development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick start
+
+### 1. Create a Personal Access Token
+
+Go to `https://dev.azure.com/{your-org}/_usersSettings/tokens` and create a token with the **Work Items → Read** scope.
+
+Export it as an environment variable:
+
+```bash
+export AZURE_DEVOPS_PAT="your-token-here"
+```
+
+### 2. Run the setup wizard
+
+```bash
+azwork --setup
+```
+
+This creates `~/.azwork.yml` interactively.
+
+### 3. Launch
+
+```bash
+azwork
+```
+
+## Usage
+
+```bash
+# Use defaults from ~/.azwork.yml
+azwork
+
+# Override org and project
+azwork --org myorg --project myproject
+
+# Custom export directory
+azwork --output-dir ./sprint-bugs
+
+# Re-run setup
+azwork --setup
+```
+
+## Configuration
+
+azwork reads its configuration from `~/.azwork.yml`. CLI arguments always take priority.
+
+### `~/.azwork.yml` anatomy
+
+```yaml
+# Azure DevOps organization name (the {org} part of dev.azure.com/{org})
+org: myorg
+
+# Project name within the organization
+project: myproject
+
+# Default directory where exported Markdown files are saved.
+# Can be an absolute path or relative to where you run azwork.
+# Created automatically on first export if it doesn't exist.
+default_output_dir: ./bugs
+
+# Work item types to include in queries.
+# These are used both as WIQL filter and as options in the Type dropdown.
+# Common values: Bug, Task, User Story, Epic, Feature, Issue, Test Case
+work_item_types:
+  - Bug
+  - Task
+  - User Story
+```
+
+All fields are optional when using CLI overrides. The PAT is **never** stored in the config file — it is always read from the `AZURE_DEVOPS_PAT` environment variable.
+
+### Minimal example
+
+```yaml
+org: contoso
+project: webapp
+```
+
+### Full example
+
+```yaml
+org: contoso
+project: webapp
+default_output_dir: ~/work/bugs
+work_item_types:
+  - Bug
+  - Task
+  - User Story
+  - Feature
+  - Epic
+```
+
+## Keybindings
+
+### List screen
+
+| Key | Action |
+|-----|--------|
+| `↑` `↓` | Navigate rows |
+| `Enter` | Open detail view |
+| `E` | Export highlighted item to Markdown |
+| `R` | Refresh (re-fetch from API) |
+| `Q` | Quit |
+| `?` | Show help |
+
+Column headers are clickable to sort by that column.
+
+### Detail screen
+
+| Key | Action |
+|-----|--------|
+| `Esc` | Back to list |
+| `E` | Export as Markdown |
+| `P` | Export as Claude Code prompt |
+| `C` | Copy Markdown to clipboard |
+| `O` | Open in browser |
+| `?` | Show help |
+
+## Export formats
+
+### Markdown
+
+A structured Markdown file with metadata table, description, repro steps, acceptance criteria, discussion thread, related items, and custom fields.
+
+```
+bugs/1234-login-fails-special-chars.md
+```
+
+### Claude Code prompt
+
+Same Markdown content wrapped in a prompt template that instructs Claude Code to analyze and resolve the work item:
+
+```markdown
+# Task: Resolve the following work item
+
+Analyze the work item described below and take the necessary actions to resolve it.
+The project context is described in the CLAUDE.md file at the repository root.
+
+## Work Item
+[... full work item markdown ...]
+
+## Instructions
+1. Analyze the work item and identify the affected files
+2. Implement the fix or the requested feature
+3. Write or update tests to cover the case
+4. Verify that existing tests are not broken
+5. Briefly describe the changes you made
+```
+
+## Project structure
+
+```
+azwork/
+├── __main__.py              # CLI entry point (argparse)
+├── config.py                # YAML config loading + CLI merge
+├── utils.py                 # HTML→Markdown conversion
+├── api/
+│   ├── client.py            # Azure DevOps REST client (auth, batching, cache)
+│   ├── wiql.py              # WIQL query builder
+│   └── models.py            # WorkItem, Comment, Relation dataclasses
+├── tui/
+│   ├── app.py               # Textual App
+│   ├── screens/
+│   │   ├── list_screen.py   # Work item list with filters
+│   │   └── detail_screen.py # Single item detail + export dialog
+│   └── widgets/
+│       ├── filter_bar.py    # Type / State / Iteration / Search filters
+│       └── item_table.py    # Sortable DataTable for work items
+└── export/
+    ├── markdown.py          # Markdown generation
+    └── prompt.py            # Claude Code prompt wrapper
+```
+
+## Running tests
+
+```bash
+pytest
+```
+
+Tests mock all API calls and cover:
+
+- API client (pagination, HTTP errors, caching, response parsing)
+- WIQL query construction with various filter combinations
+- Markdown export (formatting, edge cases, empty fields)
+- HTML → Markdown conversion (all supported tags)
+
+## Requirements
+
+- Python 3.10+
+- An Azure DevOps organization with work items
+- A PAT with **Work Items → Read** scope
+
+## License
+
+MIT

azwork-0.1.0/azwork/__init__.py

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

azwork-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()