azdo-cli 0.2.5 → 0.4.0

package/README.md

@@ -12,9 +12,12 @@ Azure DevOps CLI focused on work item read/write workflows.
 - Update work item state (`set-state`)
 - Assign and unassign work items (`assign`)
 - Set any work item field by reference name (`set-field`)
+- Create or update Tasks from markdown documents (`upsert`)
 - Read rich-text fields as markdown (`get-md-field`)
 - Set rich-text fields as markdown from inline text, file, or stdin (`set-md-field`)
+- Check branch pull request status, open PRs to `develop`, and review active comments (`pr`)
 - Persist org/project/default fields in local config (`config`)
+- List all fields of a work item (`list-fields`)
 - Store PAT in OS credential store (or use `AZDO_PAT`)
 
 ## Installation
@@ -47,18 +50,24 @@ azdo get-item 12345
 
 # 3) Update state
 azdo set-state 12345 "Active"
+
+# 4) Create or update a Task from markdown
+azdo upsert --content $'---\nTitle: Improve markdown import UX\nState: New\n---'
 ```
 
 ## Command Cheat Sheet
 
 | Command | Purpose | Common Flags |
 | --- | --- | --- |
-| `azdo get-item <id>` | Read a work item | `--short`, `--fields`, `--org`, `--project` |
+| `azdo get-item <id>` | Read a work item | `--short`, `--fields`, `--markdown`, `--org`, `--project` |
 | `azdo set-state <id> <state>` | Change work item state | `--json`, `--org`, `--project` |
 | `azdo assign <id> [name]` | Assign or unassign owner | `--unassign`, `--json`, `--org`, `--project` |
 | `azdo set-field <id> <field> <value>` | Update any field | `--json`, `--org`, `--project` |
+| `azdo upsert [id]` | Create or update a Task from markdown | `--content`, `--file`, `--json`, `--org`, `--project` |
 | `azdo get-md-field <id> <field>` | Get field as markdown | `--org`, `--project` |
 | `azdo set-md-field <id> <field> [content]` | Set markdown field | `--file`, `--json`, `--org`, `--project` |
+| `azdo list-fields <id>` | List all fields of a work item | `--json`, `--org`, `--project` |
+| `azdo pr <subcommand>` | Manage pull requests for the current branch | `status`, `open`, `comments`, `--json`, `--org`, `--project` |
 | `azdo config <subcommand>` | Manage saved settings | `set`, `get`, `list`, `unset`, `wizard`, `--json` |
 | `azdo clear-pat` | Remove stored PAT | none |
 
@@ -75,6 +84,12 @@ azdo get-item 12345 --short
 
 # Include extra fields for this call
 azdo get-item 12345 --fields "System.Tags,Microsoft.VSTS.Common.Priority"
+
+# Convert rich text fields to markdown
+azdo get-item 12345 --markdown
+
+# Disable markdown even if config is on
+azdo get-item 12345 --no-markdown
 ```
 
 ```bash
@@ -89,6 +104,24 @@ azdo assign 12345 --unassign
 azdo set-field 12345 System.Title "Updated title"
 ```
 
+### List Fields
+
+```bash
+# List all fields with values (rich text fields preview first 5 lines)
+azdo list-fields 12345
+
+# JSON output
+azdo list-fields 12345 --json
+```
+
+### Markdown Display
+
+The `get-item` command can convert HTML rich-text fields to readable markdown. Resolution order:
+
+1. `--markdown` / `--no-markdown` flag (highest priority)
+2. Config setting: `azdo config set markdown true`
+3. Default: off (HTML stripped to plain text)
+
 ### Markdown Field Commands
 
 ```bash
@@ -105,6 +138,120 @@ azdo set-md-field 12345 System.Description --file ./description.md
 cat description.md | azdo set-md-field 12345 System.Description
 ```
 
+### Pull Request Commands
+
+The `pr` command group uses the current git branch and the Azure DevOps `origin` remote automatically. It requires a PAT with `Code (Read)` scope for read operations and `Code (Read & Write)` for pull request creation.
+
+```bash
+# Check whether the current branch already has pull requests
+azdo pr status
+
+# Open a pull request to develop
+azdo pr open --title "Add PR handling" --description "Implements pr status, pr open, pr comments commands"
+
+# Review active comments for the current branch's active pull request
+azdo pr comments
+```
+
+`azdo pr status`
+
+- Lists all pull requests for the current branch, including active, completed, and abandoned PRs
+- Prints `No pull requests found for branch <branch>.` when no PRs exist
+- Supports `--json` for machine-readable output
+
+`azdo pr open`
+
+- Requires both `--title <title>` and `--description <description>`
+- Targets `develop` automatically
+- Creates a new active pull request when none exists
+- Reuses the existing active PR when one already matches the branch and target
+- Fails with a clear error when run from `develop` or when multiple active PRs already exist
+
+`azdo pr comments`
+
+- Resolves the single active pull request for the current branch
+- Returns only active or pending threads with visible, non-deleted comments
+- Groups text output by thread and shows file context when available
+- Prints `Pull request #<id> has no active comments.` when the PR has no active comment threads
+- Fails instead of guessing when no active PR or multiple active PRs exist
+
+## azdo upsert
+
+`azdo upsert` accepts a single markdown task document and either creates a new Azure DevOps Task or updates an existing one. Omit `[id]` to create; pass `[id]` to update that work item in place.
+
+```bash
+# Create from inline content
+azdo upsert --content $'---\nTitle: Improve markdown import UX\nAssigned To: user@example.com\nState: New\n---'
+
+# Update from a file
+azdo upsert 12345 --file ./task-import.md
+
+# JSON output
+azdo upsert 12345 --content $'---\nSystem.Title: Improve markdown import UX\n---' --json
+```
+
+The command requires exactly one source flag:
+
+- `azdo upsert [id] --content <markdown>`
+- `azdo upsert [id] --file <path>`
+
+If `--file` succeeds, the source file is deleted after the Azure DevOps write completes. If parsing, validation, or the API call fails, the file is preserved. If deletion fails after a successful write, the command still succeeds and prints a warning.
+
+### Task Document Format
+
+The document starts with YAML front matter for scalar fields, followed by optional `##` heading sections for markdown rich-text fields.
+
+```md
+---
+Title: Improve markdown import UX
+Assigned To: user@example.com
+State: New
+Tags: cli; markdown
+Priority: null
+---
+
+## Description
+
+Implement a single-command task import flow.
+
+## Acceptance Criteria
+
+- Supports create when no ID is passed
+- Supports update when an ID is passed
+- Deletes imported files only after success
+```
+
+Supported friendly field names:
+
+- `Title`
+- `Assigned To` / `assignedTo`
+- `State`
+- `Description`
+- `Acceptance Criteria` / `acceptanceCriteria`
+- `Tags`
+- `Priority`
+
+Raw Azure DevOps reference names are also accepted anywhere a field name is expected, for example `System.Title` or `Microsoft.VSTS.Common.AcceptanceCriteria`.
+
+Clear semantics:
+
+- Scalar YAML fields with `null` or an empty value are treated as clears on update.
+- Rich-text heading sections with an empty body are treated as clears on update.
+- Omitted fields are untouched on update.
+
+`--json` output shape:
+
+```json
+{
+  "action": "created",
+  "id": 12345,
+  "fields": {
+    "System.Title": "Improve markdown import UX",
+    "System.Description": "Implement a single-command task import flow."
+  }
+}
+```
+
 ### Configuration
 
 ```bash
@@ -114,6 +261,9 @@ azdo config list
 # Interactive setup
 azdo config wizard
 
+# Enable markdown display for all get-item calls
+azdo config set markdown true
+
 # Set/get/unset values
 azdo config set fields "System.Tags,Custom.Priority"
 azdo config get fields
@@ -133,6 +283,7 @@ azdo clear-pat
 ## JSON Output
 
 These commands support `--json` for machine-readable output:
+- `list-fields`
 - `set-state`
 - `assign`
 - `set-field`