azdo-cli 0.2.0-develop.8 → 0.2.0-develop.89

package/README.md

@@ -1,79 +1,268 @@
-# bd - Beads
+# azdo-cli
 
-**Distributed, git-backed graph issue tracker for AI agents.**
+Azure DevOps CLI focused on work item read/write workflows.
 
-**Platforms:** macOS, Linux, Windows, FreeBSD
+[![npm version](https://img.shields.io/npm/v/azdo-cli)](https://www.npmjs.com/package/azdo-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=alkampfergit_azdo-cli&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=alkampfergit_azdo-cli)
 
-[![License](https://img.shields.io/github/license/steveyegge/beads)](LICENSE)
-[![Go Report Card](https://goreportcard.com/badge/github.com/steveyegge/beads)](https://goreportcard.com/report/github.com/steveyegge/beads)
-[![Release](https://img.shields.io/github/v/release/steveyegge/beads)](https://github.com/steveyegge/beads/releases)
-[![npm version](https://img.shields.io/npm/v/@beads/bd)](https://www.npmjs.com/package/@beads/bd)
-[![PyPI](https://img.shields.io/pypi/v/beads-mcp)](https://pypi.org/project/beads-mcp/)
+## Features
 
-Beads provides a persistent, structured memory for coding agents. It replaces messy markdown plans with a dependency-aware graph, allowing agents to handle long-horizon tasks without losing context.
+- Retrieve work items with readable output (`get-item`)
+- 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`)
+- Persist org/project/default fields in local config (`config`)
+- Store PAT in OS credential store (or use `AZDO_PAT`)
 
-## ⚡ Quick Start
+## Installation
 
 ```bash
-# Install beads CLI (system-wide - don't clone this repo into your project)
-curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
+npm install -g azdo-cli
+```
+
+## Authentication and Context Resolution
+
+PAT resolution order:
+1. `AZDO_PAT` environment variable
+2. Stored credential from OS keyring
+3. Interactive PAT prompt (then stored for next runs)
 
-# Initialize in YOUR project
-cd your-project
-bd init
+Org/project resolution order:
+1. `--org` + `--project` flags
+2. Saved config (`azdo config set org ...`, `azdo config set project ...`)
+3. Azure DevOps `origin` git remote auto-detection
 
-# Tell your agent
-echo "Use 'bd' for task tracking" >> AGENTS.md
+## Quick Start
+
+```bash
+# 1) Configure defaults once
+azdo config set org myorg
+azdo config set project myproject
+
+# 2) Read a work item
+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---'
 ```
 
-**Note:** Beads is a CLI tool you install once and use everywhere. You don't need to clone this repository into your project.
+## Command Cheat Sheet
 
-## 🛠 Features
+| Command | Purpose | Common Flags |
+| --- | --- | --- |
+| `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 config <subcommand>` | Manage saved settings | `set`, `get`, `list`, `unset`, `wizard`, `--json` |
+| `azdo clear-pat` | Remove stored PAT | none |
 
-* **Git as Database:** Issues stored as JSONL in `.beads/`. Versioned, branched, and merged like code.
-* **Agent-Optimized:** JSON output, dependency tracking, and auto-ready task detection.
-* **Zero Conflict:** Hash-based IDs (`bd-a1b2`) prevent merge collisions in multi-agent/multi-branch workflows.
-* **Invisible Infrastructure:** SQLite local cache for speed; background daemon for auto-sync.
-* **Compaction:** Semantic "memory decay" summarizes old closed tasks to save context window.
+## Command Reference
 
-## 📖 Essential Commands
+### Core
 
-| Command | Action |
-| --- | --- |
-| `bd ready` | List tasks with no open blockers. |
-| `bd create "Title" -p 0` | Create a P0 task. |
-| `bd update <id> --claim` | Atomically claim a task (sets assignee + in_progress). |
-| `bd dep add <child> <parent>` | Link tasks (blocks, related, parent-child). |
-| `bd show <id>` | View task details and audit trail. |
+```bash
+# Get full work item
+azdo get-item 12345
+
+# Get short view
+azdo get-item 12345 --short
+
+# Include extra fields for this call
+azdo get-item 12345 --fields "System.Tags,Microsoft.VSTS.Common.Priority"
 
-## 🔗 Hierarchy & Workflow
+# Convert rich text fields to markdown
+azdo get-item 12345 --markdown
+
+# Disable markdown even if config is on
+azdo get-item 12345 --no-markdown
+```
 
-Beads supports hierarchical IDs for epics:
+```bash
+# Set state
+azdo set-state 12345 "Closed"
+
+# Assign / unassign
+azdo assign 12345 "someone@company.com"
+azdo assign 12345 --unassign
+
+# Set generic field
+azdo set-field 12345 System.Title "Updated title"
+```
+
+### 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
+# Read field and auto-convert HTML -> markdown
+azdo get-md-field 12345 System.Description
+
+# Set markdown inline
+azdo set-md-field 12345 System.Description "# Title\n\nSome **bold** text"
+
+# Set markdown from file
+azdo set-md-field 12345 System.Description --file ./description.md
+
+# Set markdown from stdin
+cat description.md | azdo set-md-field 12345 System.Description
+```
+
+## 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
+```
 
-* `bd-a3f8` (Epic)
-* `bd-a3f8.1` (Task)
-* `bd-a3f8.1.1` (Sub-task)
+The command requires exactly one source flag:
 
-**Stealth Mode:** Run `bd init --stealth` to use Beads locally without committing files to the main repo. Perfect for personal use on shared projects.
+- `azdo upsert [id] --content <markdown>`
+- `azdo upsert [id] --file <path>`
 
-**Contributor vs Maintainer:** When working on open-source projects:
+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.
 
-* **Contributors** (forked repos): Run `bd init --contributor` to route planning issues to a separate repo (e.g., `~/.beads-planning`). Keeps experimental work out of PRs.
-* **Maintainers** (write access): Beads auto-detects maintainer role via SSH URLs or HTTPS with credentials. Only need `git config beads.role maintainer` if using GitHub HTTPS without credentials but you have write access.
+### Task Document Format
 
-## 📦 Installation
+The document starts with YAML front matter for scalar fields, followed by optional `##` heading sections for markdown rich-text fields.
 
-* **npm:** `npm install -g @beads/bd`
-* **Homebrew:** `brew install beads`
-* **Go:** `go install github.com/steveyegge/beads/cmd/bd@latest`
+```md
+---
+Title: Improve markdown import UX
+Assigned To: user@example.com
+State: New
+Tags: cli; markdown
+Priority: null
+---
 
-**Requirements:** Linux, FreeBSD, macOS, or Windows.
+## Description
 
-## 🌐 Community Tools
+Implement a single-command task import flow.
 
-See [docs/COMMUNITY_TOOLS.md](docs/COMMUNITY_TOOLS.md) for a curated list of community-built UIs, extensions, and integrations—including terminal interfaces, web UIs, editor extensions, and native apps.
+## 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
+# List settings
+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
+azdo config unset fields
+
+# JSON output
+azdo config list --json
+```
+
+### Credential Management
+
+```bash
+# Remove stored PAT from keyring
+azdo clear-pat
+```
+
+## JSON Output
+
+These commands support `--json` for machine-readable output:
+- `set-state`
+- `assign`
+- `set-field`
+- `set-md-field`
+- `config set|get|list|unset`
+
+## Development
+
+### Prerequisites
+
+- Node.js LTS (20+)
+- npm
+
+### Setup
+
+```bash
+git clone https://github.com/alkampfergit/azdo-cli.git
+cd azdo-cli
+npm install
+```
+
+### Scripts
+
+| Command | Description |
+| --- | --- |
+| `npm run build` | Build the CLI with tsup |
+| `npm test` | Build and run tests with vitest |
+| `npm run lint` | Lint source files with ESLint |
+| `npm run typecheck` | Type-check with tsc (no emit) |
+| `npm run format` | Check formatting with Prettier |
 
-## 📝 Documentation
+## License
 
-* [Installing](docs/INSTALLING.md) | [Agent Workflow](AGENT_INSTRUCTIONS.md) | [Copilot Setup](docs/COPILOT_INTEGRATION.md) | [Articles](ARTICLES.md) | [Sync Branch Mode](docs/PROTECTED_BRANCHES.md) | [Troubleshooting](docs/TROUBLESHOOTING.md) | [FAQ](docs/FAQ.md)
-* [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/steveyegge/beads)
+[MIT](LICENSE)