azdo-cli 0.8.0-develop.167 → 0.8.0-develop.176

package/README.md

@@ -9,13 +9,10 @@ Azure DevOps CLI focused on work item read/write workflows.
 ## 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`)
+- Update work item state, assignee, or any field (`set-state`, `assign`, `set-field`)
 - Create or update work items from markdown documents (`upsert`)
 - Read and post work item comments (`comments`)
-- Read rich-text fields as markdown (`get-md-field`)
-- Set rich-text fields as markdown from inline text, file, or stdin (`set-md-field`)
+- Read/write rich-text fields as markdown (`get-md-field`, `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`)
@@ -27,360 +24,35 @@ Azure DevOps CLI focused on work item read/write workflows.
 npm install -g azdo-cli
 ```
 
-## Utility Scripts
-
-The repository also includes a helper script for syncing local `.env` entries into GitHub Actions secrets for the current repository:
-
-```bash
-./scripts/sync-env-to-gh-secrets.zsh
-```
-
-It walks upward from the current directory until it finds a `.env`, then sets each valid `KEY=VALUE` entry with `gh secret set`. You can also limit the sync to selected keys:
-
-```bash
-./scripts/sync-env-to-gh-secrets.zsh FOO BAR
-```
-
-## 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
+# Configure defaults once
 azdo config set org myorg
 azdo config set project myproject
 
-# 2) Read a work item
+# Read a work item
 azdo get-item 12345
 
-# 3) Update state
+# Update state
 azdo set-state 12345 "Active"
 
-# 4) Create or update a work item from markdown
+# Create a work item from markdown
 azdo upsert --type "User Story" --content $'---\nTitle: Improve markdown import UX\nState: New\n---'
 
-# 5) Review work item discussion and post an update
+# Read and post comments
 azdo comments list 12345
 azdo comments add 12345 "Investigating the root cause now."
 ```
 
-## Command Cheat Sheet
-
-| 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 work item from markdown | `--content`, `--file`, `--type`, `--json`, `--org`, `--project` |
-| `azdo comments <subcommand>` | Read or add work item comments | `list`, `add`, `--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 |
-
-## Command Reference
-
-### Core
-
-```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"
-
-# Convert rich text fields to markdown
-azdo get-item 12345 --markdown
-
-```
-
-```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"
-```
-
-### 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` flag enables markdown for the current call
-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
-```
-
-### 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 pull requests for the current branch
-- Includes Azure DevOps pull request checks under each returned pull request
-- Prints `Checks: none reported by Azure DevOps` when a pull request has no returned checks
-- Shows `Detail: ...` lines for failed or errored checks when Azure DevOps provides description text
-- Prints `No pull requests found for branch <branch>.` when no PRs exist
-- Supports `--json` for machine-readable output, including a `checks` array per pull request
-
-`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
-
-### Work Item Comment Commands
-
-The `comments` command group works on a specific work item ID. It requires a PAT with `Work Items (read)` scope for listing comments and `Work Items (Read & Write)` to add a new comment.
-
-```bash
-# Read the visible comment history for a work item
-azdo comments list 12345
-
-# Read the same history as JSON
-azdo comments list 12345 --json
-
-# Post a progress update
-azdo comments add 12345 "Investigation complete. Working on the fix next."
-
-# Post the update and return JSON
-azdo comments add 12345 "Queued validation run." --json
-```
-
-`azdo comments list`
-
-- Resolves the target work item directly from the provided ID
-- Retrieves the full visible comment history and follows Azure DevOps pagination internally
-- Prints comments newest first with comment ID, author, timestamp, and body text
-- Prints `Work item #<id> has no comments.` when the work item has no visible comments
-
-`azdo comments add`
-
-- Requires a non-empty `<text>` positional argument
-- Preserves the supplied comment text as the submitted body
-- Prints `Added comment #<commentId> to work item #<id>` on success
-- Fails locally before any API call when the text is empty or whitespace-only
-
-## azdo upsert
-
-`azdo upsert` accepts a single markdown work-item document and either creates a new Azure DevOps work item or updates an existing one. Omit `[id]` to create; pass `[id]` to update that work item in place. Create mode defaults to `Task`, and `--type <work item type>` lets you create `Bug`, `User Story`, `Feature`, `Epic`, and other Azure DevOps work item types.
-
-```bash
-# Create a Bug from inline content
-azdo upsert --type Bug --content $'---\nTitle: Improve markdown import UX\nAssigned To: user@example.com\nState: New\n---'
-
-# Preserve the default Task create behavior
-azdo upsert --content $'---\nTitle: Follow-up task\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>`
-- `azdo upsert --type <work-item-type> --content <markdown>`
-
-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.
-
-Type rules:
-
-- `--type` is optional for create and defaults to `Task`.
-- `--type` is only valid when creating a new work item.
-- Human-readable and JSON success output include the resulting work item type.
-
-### 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,
-  "workItemType": "User Story",
-  "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:
-- `list-fields`
-- `set-state`
-- `assign`
-- `set-field`
-- `set-md-field`
-- `upsert`
-- `comments list|add`
-- `pr status|open|comments`
-- `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
+## Documentation
 
-| 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 |
+| Topic | File |
+|-------|------|
+| Authentication & PAT storage | [docs/authentication.md](docs/authentication.md) |
+| Linux credential store setup | [docs/linux-credential-store.md](docs/linux-credential-store.md) |
+| Full command reference | [docs/commands.md](docs/commands.md) |
+| Development setup | [docs/development.md](docs/development.md) |
 
 ## License
 

package/dist/index.js

@@ -263,8 +263,10 @@ async function listWorkItemComments(context, id, pat) {
     comments
   };
 }
-async function addWorkItemComment(context, id, pat, text) {
-  const response = await fetchWithErrors(buildWorkItemCommentsUrl(context, id).toString(), {
+async function addWorkItemComment(context, id, pat, text, format = "html") {
+  const url = buildWorkItemCommentsUrl(context, id);
+  url.searchParams.set("format", format);
+  const response = await fetchWithErrors(url.toString(), {
     method: "POST",
     headers: {
       ...authHeaders(pat),
@@ -329,6 +331,8 @@ async function applyWorkItemPatch(context, id, pat, operations) {
 
 // src/services/auth.ts
 import { createInterface } from "readline";
+import { existsSync, readFileSync as readFileSync2 } from "fs";
+import { dirname as dirname2, join } from "path";
 
 // src/services/credential-store.ts
 import { Entry } from "@napi-rs/keyring";
@@ -346,7 +350,9 @@ async function storePat(pat) {
   try {
     const entry = new Entry(SERVICE, ACCOUNT);
     entry.setPassword(pat);
+    return true;
   } catch {
+    return false;
   }
 }
 async function deletePat() {
@@ -360,10 +366,19 @@ async function deletePat() {
 }
 
 // src/services/auth.ts
+var PAT_PROMPT = "Enter your Azure DevOps PAT: ";
+var VISIBLE_CHARS = 5;
 function normalizePat(rawPat) {
   const trimmedPat = rawPat.trim();
   return trimmedPat.length > 0 ? trimmedPat : null;
 }
+function maskedDisplay(pat) {
+  if (pat.length <= VISIBLE_CHARS * 2) {
+    return pat;
+  }
+  const hiddenCount = pat.length - VISIBLE_CHARS * 2;
+  return pat.slice(0, VISIBLE_CHARS) + "*".repeat(hiddenCount) + pat.slice(-VISIBLE_CHARS);
+}
 async function promptForPat() {
   if (!process.stdin.isTTY) {
     return null;
@@ -373,10 +388,13 @@ async function promptForPat() {
       input: process.stdin,
       output: process.stderr
     });
-    process.stderr.write("Enter your Azure DevOps PAT: ");
+    process.stderr.write(PAT_PROMPT);
     process.stdin.setRawMode(true);
     process.stdin.resume();
     let pat = "";
+    const redraw = () => {
+      process.stderr.write(`\r${PAT_PROMPT}${maskedDisplay(pat)}\x1B[K`);
+    };
     const onData = (key) => {
       const ch = key.toString("utf8");
       if (ch === "") {
@@ -394,17 +412,37 @@ async function promptForPat() {
       } else if (ch === "\x7F" || ch === "\b") {
         if (pat.length > 0) {
           pat = pat.slice(0, -1);
-          process.stderr.write("\b \b");
+          redraw();
         }
       } else {
         pat += ch;
-        process.stderr.write("*".repeat(ch.length));
+        redraw();
       }
     };
     process.stdin.on("data", onData);
   });
 }
-async function resolvePat() {
+function findDotEnvPat(startDir = process.cwd()) {
+  let current = startDir;
+  while (true) {
+    const envFile = join(current, ".env");
+    if (existsSync(envFile)) {
+      const contents = readFileSync2(envFile, "utf8");
+      for (const line of contents.split("\n")) {
+        const match = line.match(/^AZDO_PAT\s*=\s*(.+)$/);
+        if (match) {
+          const value = match[1].trim().replace(/^["']|["']$/g, "");
+          if (value.length > 0) return value;
+        }
+      }
+    }
+    const parent = dirname2(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return null;
+}
+async function resolvePat(promptFn = promptForPat) {
   const envPat = process.env.AZDO_PAT;
   if (envPat) {
     return { pat: envPat, source: "env" };
@@ -413,11 +451,18 @@ async function resolvePat() {
   if (storedPat !== null) {
     return { pat: storedPat, source: "credential-store" };
   }
-  const promptedPat = await promptForPat();
+  const dotEnvPat = findDotEnvPat();
+  if (dotEnvPat !== null) {
+    return { pat: dotEnvPat, source: "env" };
+  }
+  const promptedPat = await promptFn();
   if (promptedPat !== null) {
     const normalizedPat = normalizePat(promptedPat);
     if (normalizedPat !== null) {
-      await storePat(normalizedPat);
+      const saved = await storePat(normalizedPat);
+      if (!saved) {
+        process.stderr.write("Warning: Could not save PAT to credential store. You may need to enter it again next time.\n");
+      }
       return { pat: normalizedPat, source: "prompt" };
     }
   }
@@ -1196,7 +1241,7 @@ function createGetMdFieldCommand() {
 }
 
 // src/commands/set-md-field.ts
-import { existsSync, readFileSync as readFileSync2 } from "fs";
+import { existsSync as existsSync2, readFileSync as readFileSync3 } from "fs";
 import { Command as Command8 } from "commander";
 function fail(message) {
   process.stderr.write(`Error: ${message}
@@ -1216,11 +1261,11 @@ function resolveContent(inlineContent, options) {
   return null;
 }
 function readFileContent(filePath) {
-  if (!existsSync(filePath)) {
+  if (!existsSync2(filePath)) {
     fail(`File not found: ${filePath}`);
   }
   try {
-    return readFileSync2(filePath, "utf-8");
+    return readFileSync3(filePath, "utf-8");
   } catch {
     fail(`Cannot read file: ${filePath}`);
   }
@@ -1284,7 +1329,7 @@ function createSetMdFieldCommand() {
 }
 
 // src/commands/upsert.ts
-import { existsSync as existsSync2, readFileSync as readFileSync3, unlinkSync } from "fs";
+import { existsSync as existsSync3, readFileSync as readFileSync4, unlinkSync } from "fs";
 import { Command as Command9 } from "commander";
 
 // src/services/task-document.ts
@@ -1448,12 +1493,12 @@ function loadSourceContent(options) {
     return { content: options.content };
   }
   const filePath = options.file;
-  if (!existsSync2(filePath)) {
+  if (!existsSync3(filePath)) {
     fail2(`File not found: ${filePath}`);
   }
   try {
     return {
-      content: readFileSync3(filePath, "utf-8"),
+      content: readFileSync4(filePath, "utf-8"),
       sourceFile: filePath
     };
   } catch {
@@ -2055,16 +2100,17 @@ function formatCommentHeader(comment) {
   const timestamp = comment.modifiedAt ?? comment.createdAt ?? "Unknown time";
   return `Comment #${comment.id} by ${author} at ${timestamp}`;
 }
-function formatComments(result) {
+function formatComments(result, convertMarkdown) {
   const lines = [`Comments for work item #${result.workItemId}`];
   for (const comment of result.comments) {
-    lines.push("", formatCommentHeader(comment), comment.text);
+    const text = convertMarkdown ? toMarkdown(comment.text) : comment.text;
+    lines.push("", formatCommentHeader(comment), text);
   }
   return lines.join("\n");
 }
 function createCommentsListCommand() {
   const command = new Command12("list");
-  command.description("List visible comments for a work item").argument("<id>", "work item ID").option("--org <org>", "Azure DevOps organization").option("--project <project>", "Azure DevOps project").option("--json", "output JSON").action(async (idStr, options) => {
+  command.description("List visible comments for a work item").argument("<id>", "work item ID").option("--org <org>", "Azure DevOps organization").option("--project <project>", "Azure DevOps project").option("--json", "output JSON").option("--markdown", "convert HTML comment bodies to markdown").action(async (idStr, options) => {
     validateOrgProjectPair(options);
     const id = parseWorkItemId(idStr);
     let context;
@@ -2082,7 +2128,7 @@ function createCommentsListCommand() {
 `);
         return;
       }
-      process.stdout.write(`${formatComments(result)}
+      process.stdout.write(`${formatComments(result, options.markdown === true)}
 `);
     } catch (err) {
       handleCommandError(err, id, context, "read");
@@ -2092,7 +2138,7 @@ function createCommentsListCommand() {
 }
 function createCommentsAddCommand() {
   const command = new Command12("add");
-  command.description("Add a comment to a work item").argument("<id>", "work item ID").argument("<text>", "comment text").option("--org <org>", "Azure DevOps organization").option("--project <project>", "Azure DevOps project").option("--json", "output JSON").action(async (idStr, text, options) => {
+  command.description("Add a comment to a work item").argument("<id>", "work item ID").argument("<text>", "comment text").option("--org <org>", "Azure DevOps organization").option("--project <project>", "Azure DevOps project").option("--json", "output JSON").option("--markdown", "post comment as markdown").action(async (idStr, text, options) => {
     validateOrgProjectPair(options);
     const id = parseWorkItemId(idStr);
     if (text.trim() === "") {
@@ -2102,7 +2148,8 @@ function createCommentsAddCommand() {
     try {
       context = resolveContext(options);
       const credential = await resolvePat();
-      const result = await addWorkItemComment(context, id, credential.pat, text);
+      const format = options.markdown === true ? "markdown" : "html";
+      const result = await addWorkItemComment(context, id, credential.pat, text, format);
       if (options.json) {
         process.stdout.write(`${JSON.stringify(result, null, 2)}
 `);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "azdo-cli",
-  "version": "0.8.0-develop.167",
+  "version": "0.8.0-develop.176",
   "description": "Azure DevOps CLI tool",
   "type": "module",
   "bin": {