azdo-cli 0.2.0 → 0.2.5

package/README.md

@@ -1,31 +1,143 @@
 # azdo-cli
 
-A command-line interface for Azure DevOps.
+Azure DevOps CLI focused on work item read/write workflows.
 
 [![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)
 
+## Features
+
+- 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`)
+- 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`)
+
 ## Installation
 
 ```bash
 npm install -g azdo-cli
 ```
 
-## Usage
+## 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)
+
+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
+
+## 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"
+```
+
+## Command Cheat Sheet
+
+| Command | Purpose | Common Flags |
+| --- | --- | --- |
+| `azdo get-item <id>` | Read a work item | `--short`, `--fields`, `--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 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 |
+
+## Command Reference
+
+### Core
 
 ```bash
-# Show help
-azdo --help
+# Get full work item
+azdo get-item 12345
 
-# Show version
-azdo --version
-azdo -v
+# 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"
 ```
 
-## Current Status
+```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 Field Commands
+
+```bash
+# Read field and auto-convert HTML -> markdown
+azdo get-md-field 12345 System.Description
 
-This project is in early development (v0.2.0). The base CLI scaffold is in place with support for `--help` and `--version`. Azure DevOps commands (work items, pipelines, repos, etc.) will be added in future releases.
+# 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
+```
+
+### Configuration
+
+```bash
+# List settings
+azdo config list
+
+# Interactive setup
+azdo config wizard
+
+# 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
 
@@ -47,27 +159,11 @@ npm install
 | Command | Description |
 | --- | --- |
 | `npm run build` | Build the CLI with tsup |
-| `npm test` | Run tests with vitest |
+| `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 |
 
-### Tech Stack
-
-- **TypeScript 5.x** (strict mode, ES modules)
-- **commander.js** — CLI framework
-- **tsup** — Bundler (single-file ESM output)
-- **vitest** — Test runner
-- **ESLint + Prettier** — Linting and formatting
-
-### Branch Strategy
-
-This project follows **GitFlow**:
-
-- `master` — stable releases
-- `develop` — integration branch
-- `feature/*` — feature branches off `develop`
-
 ## License
 
 [MIT](LICENSE)

package/dist/index.js

@@ -42,6 +42,19 @@ async function fetchWithErrors(url, init) {
   if (response.status === 404) throw new Error("NOT_FOUND");
   return response;
 }
+async function readResponseMessage(response) {
+  try {
+    const body = await response.json();
+    if (typeof body.message === "string" && body.message.trim() !== "") {
+      return body.message.trim();
+    }
+  } catch {
+  }
+  return null;
+}
+function normalizeFieldList(fields) {
+  return Array.from(new Set(fields.map((f) => f.trim()).filter((f) => f.length > 0)));
+}
 function buildExtraFields(fields, requested) {
   const result = {};
   for (const name of requested) {
@@ -57,11 +70,18 @@ async function getWorkItem(context, id, pat, extraFields) {
     `https://dev.azure.com/${encodeURIComponent(context.org)}/${encodeURIComponent(context.project)}/_apis/wit/workitems/${id}`
   );
   url.searchParams.set("api-version", "7.1");
-  if (extraFields && extraFields.length > 0) {
-    const allFields = [...DEFAULT_FIELDS, ...extraFields];
+  const normalizedExtraFields = extraFields ? normalizeFieldList(extraFields) : [];
+  if (normalizedExtraFields.length > 0) {
+    const allFields = normalizeFieldList([...DEFAULT_FIELDS, ...normalizedExtraFields]);
     url.searchParams.set("fields", allFields.join(","));
   }
   const response = await fetchWithErrors(url.toString(), { headers: authHeaders(pat) });
+  if (response.status === 400) {
+    const serverMessage = await readResponseMessage(response);
+    if (serverMessage) {
+      throw new Error(`BAD_REQUEST: ${serverMessage}`);
+    }
+  }
   if (!response.ok) {
     throw new Error(`HTTP_${response.status}`);
   }
@@ -93,7 +113,7 @@ async function getWorkItem(context, id, pat, extraFields) {
     areaPath: data.fields["System.AreaPath"],
     iterationPath: data.fields["System.IterationPath"],
     url: data._links.html.href,
-    extraFields: extraFields && extraFields.length > 0 ? buildExtraFields(data.fields, extraFields) : null
+    extraFields: normalizedExtraFields.length > 0 ? buildExtraFields(data.fields, normalizedExtraFields) : null
   };
 }
 async function getWorkItemFieldValue(context, id, pat, fieldName) {
@@ -103,6 +123,12 @@ async function getWorkItemFieldValue(context, id, pat, fieldName) {
   url.searchParams.set("api-version", "7.1");
   url.searchParams.set("fields", fieldName);
   const response = await fetchWithErrors(url.toString(), { headers: authHeaders(pat) });
+  if (response.status === 400) {
+    const serverMessage = await readResponseMessage(response);
+    if (serverMessage) {
+      throw new Error(`BAD_REQUEST: ${serverMessage}`);
+    }
+  }
   if (!response.ok) {
     throw new Error(`HTTP_${response.status}`);
   }
@@ -127,12 +153,7 @@ async function updateWorkItem(context, id, pat, fieldName, operations) {
     body: JSON.stringify(operations)
   });
   if (response.status === 400) {
-    let serverMessage = "Unknown error";
-    try {
-      const body = await response.json();
-      if (body.message) serverMessage = body.message;
-    } catch {
-    }
+    const serverMessage = await readResponseMessage(response) ?? "Unknown error";
     throw new Error(`UPDATE_REJECTED: ${serverMessage}`);
   }
   if (!response.ok) {
@@ -421,7 +442,7 @@ function validateOrgProjectPair(options) {
     process.exit(1);
   }
 }
-function handleCommandError(err, id, context, scope = "write") {
+function handleCommandError(err, id, context, scope = "write", exit = true) {
   const error = err instanceof Error ? err : new Error(String(err));
   const msg = error.message;
   const scopeLabel = scope === "read" ? "Work Items (read)" : "Work Items (Read & Write)";
@@ -444,6 +465,10 @@ function handleCommandError(err, id, context, scope = "write") {
     process.stderr.write(
       "Error: Could not connect to Azure DevOps. Check your network connection.\n"
     );
+  } else if (msg.startsWith("BAD_REQUEST:")) {
+    const serverMsg = msg.replace("BAD_REQUEST: ", "");
+    process.stderr.write(`Error: Request rejected: ${serverMsg}
+`);
   } else if (msg.startsWith("UPDATE_REJECTED:")) {
     const serverMsg = msg.replace("UPDATE_REJECTED: ", "");
     process.stderr.write(`Error: Update rejected: ${serverMsg}
@@ -452,10 +477,21 @@ function handleCommandError(err, id, context, scope = "write") {
     process.stderr.write(`Error: ${msg}
 `);
   }
-  process.exit(1);
+  if (exit) {
+    process.exit(1);
+  } else {
+    process.exitCode = 1;
+  }
 }
 
 // src/commands/get-item.ts
+function parseRequestedFields(raw) {
+  if (raw === void 0) return void 0;
+  const source = Array.isArray(raw) ? raw : [raw];
+  const tokens = source.flatMap((entry) => entry.split(/[,\s]+/)).map((field) => field.trim()).filter((field) => field.length > 0);
+  if (tokens.length === 0) return void 0;
+  return Array.from(new Set(tokens));
+}
 function stripHtml(html) {
   let text = html;
   text = text.replace(/<h[1-6][^>]*>(.*?)<\/h[1-6]>/gi, "\n--- $1 ---\n");
@@ -515,12 +551,12 @@ function createGetItemCommand() {
       try {
         context = resolveContext(options);
         const credential = await resolvePat();
-        const fieldsList = options.fields ? options.fields.split(",").map((f) => f.trim()) : loadConfig().fields;
+        const fieldsList = options.fields !== void 0 ? parseRequestedFields(options.fields) : parseRequestedFields(loadConfig().fields);
         const workItem = await getWorkItem(context, id, credential.pat, fieldsList);
         const output = formatWorkItem(workItem, options.short ?? false);
         process.stdout.write(output + "\n");
       } catch (err) {
-        handleCommandError(err, id, context, "read");
+        handleCommandError(err, id, context, "read", false);
       }
     }
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "azdo-cli",
-  "version": "0.2.0",
+  "version": "0.2.5",
   "description": "Azure DevOps CLI tool",
   "type": "module",
   "bin": {