azdo-cli 0.4.0 → 0.5.0-010-work-item-comments.149

package/README.md

@@ -12,7 +12,8 @@ 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`)
+- 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`)
 - Check branch pull request status, open PRs to `develop`, and review active comments (`pr`)
@@ -26,6 +27,20 @@ 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:
@@ -51,8 +66,12 @@ 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---'
+# 4) Create or update 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
+azdo comments list 12345
+azdo comments add 12345 "Investigating the root cause now."
 ```
 
 ## Command Cheat Sheet
@@ -63,7 +82,8 @@ azdo upsert --content $'---\nTitle: Improve markdown import UX\nState: New\n---'
 | `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 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` |
@@ -88,8 +108,6 @@ 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
@@ -118,7 +136,7 @@ azdo list-fields 12345 --json
 
 The `get-item` command can convert HTML rich-text fields to readable markdown. Resolution order:
 
-1. `--markdown` / `--no-markdown` flag (highest priority)
+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)
 
@@ -155,7 +173,7 @@ azdo pr comments
 
 `azdo pr status`
 
-- Lists all pull requests for the current branch, including active, completed, and abandoned PRs
+- Lists pull requests for the current branch
 - Prints `No pull requests found for branch <branch>.` when no PRs exist
 - Supports `--json` for machine-readable output
 
@@ -175,13 +193,48 @@ azdo pr comments
 - 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 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.
+`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 from inline content
-azdo upsert --content $'---\nTitle: Improve markdown import UX\nAssigned To: user@example.com\nState: New\n---'
+# 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
@@ -194,9 +247,16 @@ 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.
@@ -245,6 +305,7 @@ Clear semantics:
 {
   "action": "created",
   "id": 12345,
+  "workItemType": "User Story",
   "fields": {
     "System.Title": "Improve markdown import UX",
     "System.Description": "Implement a single-command task import flow."
@@ -288,6 +349,9 @@ These commands support `--json` for machine-readable output:
 - `assign`
 - `set-field`
 - `set-md-field`
+- `upsert`
+- `comments list|add`
+- `pr status|open|comments`
 - `config set|get|list|unset`
 
 ## Development

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { Command as Command12 } from "commander";
+import { Command as Command13 } from "commander";
 
 // src/version.ts
 import { readFileSync } from "fs";
@@ -39,7 +39,15 @@ async function fetchWithErrors(url, init) {
   }
   if (response.status === 401) throw new Error("AUTH_FAILED");
   if (response.status === 403) throw new Error("PERMISSION_DENIED");
-  if (response.status === 404) throw new Error("NOT_FOUND");
+  if (response.status === 404) {
+    let detail = "";
+    try {
+      const body = await response.text();
+      detail = ` | url=${url} | body=${body}`;
+    } catch {
+    }
+    throw new Error(`NOT_FOUND${detail}`);
+  }
   return response;
 }
 async function readResponseMessage(response) {
@@ -88,6 +96,42 @@ function writeHeaders(pat) {
     "Content-Type": "application/json-patch+json"
   };
 }
+function buildWorkItemCommentsListUrl(context, id, continuationToken) {
+  const url = new URL(
+    `https://dev.azure.com/${encodeURIComponent(context.org)}/${encodeURIComponent(context.project)}/_apis/wit/workItems/${id}/comments`
+  );
+  url.searchParams.set("api-version", "7.1-preview.4");
+  url.searchParams.set("order", "desc");
+  if (continuationToken) {
+    url.searchParams.set("continuationToken", continuationToken);
+  }
+  return url;
+}
+function buildWorkItemCommentsUrl(context, id) {
+  const url = new URL(
+    `https://dev.azure.com/${encodeURIComponent(context.org)}/${encodeURIComponent(context.project)}/_apis/wit/workItems/${id}/comments`
+  );
+  url.searchParams.set("api-version", "7.1-preview.4");
+  return url;
+}
+function mapWorkItemComment(comment, fallbackWorkItemId) {
+  return {
+    id: comment.id ?? comment.commentId ?? 0,
+    workItemId: comment.workItemId ?? fallbackWorkItemId,
+    text: typeof comment.text === "string" ? comment.text : "",
+    author: comment.createdBy?.displayName ?? null,
+    createdAt: comment.createdDate ?? null,
+    modifiedAt: comment.modifiedDate ?? null,
+    isDeleted: comment.isDeleted === true
+  };
+}
+function readContinuationToken(response, data) {
+  if (typeof data.continuationToken === "string" && data.continuationToken.trim() !== "") {
+    return data.continuationToken;
+  }
+  const headerToken = response.headers?.get("x-ms-continuationtoken") ?? response.headers?.get("continuationtoken") ?? null;
+  return headerToken && headerToken.trim() !== "" ? headerToken : null;
+}
 async function readWriteResponse(response, errorCode) {
   if (response.status === 400) {
     const serverMessage = await readResponseMessage(response) ?? "Unknown error";
@@ -196,6 +240,55 @@ async function getWorkItemFieldValue(context, id, pat, fieldName) {
   }
   return stringifyFieldValue(value);
 }
+async function listWorkItemComments(context, id, pat) {
+  const comments = [];
+  let continuationToken = null;
+  do {
+    const response = await fetchWithErrors(
+      buildWorkItemCommentsListUrl(context, id, continuationToken ?? void 0).toString(),
+      { headers: authHeaders(pat) }
+    );
+    if (!response.ok) {
+      throw new Error(`HTTP_${response.status}`);
+    }
+    const data = await response.json();
+    comments.push(
+      ...(data.comments ?? []).map((comment) => mapWorkItemComment(comment, id)).filter((comment) => !comment.isDeleted)
+    );
+    continuationToken = readContinuationToken(response, data);
+  } while (continuationToken !== null);
+  return {
+    workItemId: id,
+    count: comments.length,
+    comments
+  };
+}
+async function addWorkItemComment(context, id, pat, text) {
+  const response = await fetchWithErrors(buildWorkItemCommentsUrl(context, id).toString(), {
+    method: "POST",
+    headers: {
+      ...authHeaders(pat),
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify({ text })
+  });
+  if (response.status === 400) {
+    const serverMessage = await readResponseMessage(response) ?? "Unknown error";
+    throw new Error(`BAD_REQUEST: ${serverMessage}`);
+  }
+  if (!response.ok) {
+    throw new Error(`HTTP_${response.status}`);
+  }
+  const data = await response.json();
+  return {
+    workItemId: data.workItemId ?? id,
+    commentId: data.commentId ?? data.id ?? 0,
+    text: typeof data.text === "string" ? data.text : text,
+    author: data.createdBy?.displayName ?? null,
+    createdAt: data.createdDate ?? null,
+    url: data.url ?? null
+  };
+}
 async function updateWorkItem(context, id, pat, fieldName, operations) {
   const result = await applyWorkItemPatch(context, id, pat, operations);
   const title = result.fields["System.Title"];
@@ -633,7 +726,7 @@ function handleCommandError(err, id, context, scope = "write", exit = true) {
       `Error: Access denied. Your PAT may lack ${scope} permissions for project "${context?.project}".
 `
     );
-  } else if (msg === "NOT_FOUND") {
+  } else if (msg.startsWith("NOT_FOUND")) {
     process.stderr.write(
       `Error: Work item ${id} not found in ${context?.org}/${context?.project}.
 `
@@ -1383,7 +1476,7 @@ function buildAppliedFields(fields) {
 function ensureTitleForCreate(fields) {
   const titleField = fields.find((field) => field.refName === "System.Title");
   if (!titleField || titleField.op === "clear" || titleField.value === null || titleField.value.trim() === "") {
-    fail2("Title is required when creating a task.");
+    fail2("Title is required when creating a work item.");
   }
 }
 function writeSuccess(result, options) {
@@ -1395,7 +1488,7 @@ function writeSuccess(result, options) {
   const verb = result.action === "created" ? "Created" : "Updated";
   const fields = Object.keys(result.fields).join(", ");
   const suffix = fields ? ` (${fields})` : "";
-  process.stdout.write(`${verb} task #${result.id}${suffix}
+  process.stdout.write(`${verb} ${result.workItemType} #${result.id}${suffix}
 `);
 }
 function cleanupSourceFile(sourceFile) {
@@ -1409,16 +1502,31 @@ function cleanupSourceFile(sourceFile) {
 `);
   }
 }
-function buildUpsertResult(action, writeResult, fields) {
+function resolveCreateType(id, options) {
+  if (options.type === void 0) {
+    return "Task";
+  }
+  if (id !== void 0) {
+    fail2("--type can only be used when creating a work item.");
+  }
+  const trimmedType = options.type.trim();
+  if (trimmedType === "") {
+    fail2("--type must be a non-empty work item type.");
+  }
+  return trimmedType;
+}
+function buildUpsertResult(action, writeResult, fields, fallbackWorkItemType) {
   const appliedFields = buildAppliedFields(fields);
+  const workItemType = writeResult.fields["System.WorkItemType"];
   return {
     action,
     id: writeResult.id,
+    workItemType: typeof workItemType === "string" && workItemType.trim() !== "" ? workItemType : fallbackWorkItemType,
     fields: appliedFields
   };
 }
 function isUpdateWriteError(err) {
-  return err.message === "AUTH_FAILED" || err.message === "PERMISSION_DENIED" || err.message === "NOT_FOUND" || err.message === "NETWORK_ERROR" || err.message.startsWith("BAD_REQUEST:") || err.message.startsWith("UPDATE_REJECTED:");
+  return err.message === "AUTH_FAILED" || err.message === "PERMISSION_DENIED" || err.message.startsWith("NOT_FOUND") || err.message === "NETWORK_ERROR" || err.message.startsWith("BAD_REQUEST:") || err.message.startsWith("UPDATE_REJECTED:");
 }
 function isCreateWriteError(err) {
   return err.message === "AUTH_FAILED" || err.message === "PERMISSION_DENIED" || err.message === "NETWORK_ERROR" || err.message.startsWith("BAD_REQUEST:") || err.message.startsWith("HTTP_");
@@ -1448,10 +1556,11 @@ function handleUpsertError(err, id, context) {
 }
 function createUpsertCommand() {
   const command = new Command9("upsert");
-  command.description("Create or update a Task from a markdown document").argument("[id]", "work item ID to update; omit to create a new Task").option("--content <markdown>", "task document content").option("--file <path>", "read task document from file").option("--json", "output result as JSON").option("--org <org>", "Azure DevOps organization").option("--project <project>", "Azure DevOps project").action(async (idStr, options) => {
+  command.description("Create or update a work item from a markdown document").argument("[id]", "work item ID to update; omit to create a new work item").option("--content <markdown>", "task document content").option("--file <path>", "read task document from file").option("--type <workItemType>", "create mode work item type (defaults to Task)").option("--json", "output result as JSON").option("--org <org>", "Azure DevOps organization").option("--project <project>", "Azure DevOps project").action(async (idStr, options) => {
     validateOrgProjectPair(options);
     const id = idStr === void 0 ? void 0 : parseWorkItemId(idStr);
     const { content, sourceFile } = loadSourceContent(options);
+    const createType = resolveCreateType(id, options);
     let context;
     try {
       context = resolveContext(options);
@@ -1464,14 +1573,19 @@ function createUpsertCommand() {
       const credential = await resolvePat();
       let writeResult;
       if (action === "created") {
-        writeResult = await createWorkItem(context, "Task", credential.pat, operations);
+        writeResult = await createWorkItem(context, createType, credential.pat, operations);
       } else {
         if (id === void 0) {
           fail2("Work item ID is required for updates.");
         }
         writeResult = await applyWorkItemPatch(context, id, credential.pat, operations);
       }
-      const result = buildUpsertResult(action, writeResult, document.fields);
+      const result = buildUpsertResult(
+        action,
+        writeResult,
+        document.fields,
+        action === "created" ? createType : "Work item"
+      );
       writeSuccess(result, options);
       cleanupSourceFile(sourceFile);
     } catch (err) {
@@ -1684,7 +1798,7 @@ function handlePrCommandError(err, context, mode = "read") {
   if (error.message === "NETWORK_ERROR") {
     writeError("Could not connect to Azure DevOps. Check your network connection.");
   }
-  if (error.message === "NOT_FOUND") {
+  if (error.message.startsWith("NOT_FOUND")) {
     writeError(`Azure DevOps repository not found in ${context?.org}/${context?.project}.`);
   }
   if (error.message.startsWith("HTTP_")) {
@@ -1851,8 +1965,89 @@ function createPrCommand() {
   return command;
 }
 
+// src/commands/comments.ts
+import { Command as Command12 } from "commander";
+function writeError2(message) {
+  process.stderr.write(`Error: ${message}
+`);
+  process.exit(1);
+}
+function formatCommentHeader(comment) {
+  const author = comment.author ?? "Unknown";
+  const timestamp = comment.modifiedAt ?? comment.createdAt ?? "Unknown time";
+  return `Comment #${comment.id} by ${author} at ${timestamp}`;
+}
+function formatComments(result) {
+  const lines = [`Comments for work item #${result.workItemId}`];
+  for (const comment of result.comments) {
+    lines.push("", formatCommentHeader(comment), 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) => {
+    validateOrgProjectPair(options);
+    const id = parseWorkItemId(idStr);
+    let context;
+    try {
+      context = resolveContext(options);
+      const credential = await resolvePat();
+      const result = await listWorkItemComments(context, id, credential.pat);
+      if (options.json) {
+        process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+        return;
+      }
+      if (result.comments.length === 0) {
+        process.stdout.write(`Work item #${id} has no comments.
+`);
+        return;
+      }
+      process.stdout.write(`${formatComments(result)}
+`);
+    } catch (err) {
+      handleCommandError(err, id, context, "read");
+    }
+  });
+  return command;
+}
+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) => {
+    validateOrgProjectPair(options);
+    const id = parseWorkItemId(idStr);
+    if (text.trim() === "") {
+      writeError2("Comment text must be a non-empty string.");
+    }
+    let context;
+    try {
+      context = resolveContext(options);
+      const credential = await resolvePat();
+      const result = await addWorkItemComment(context, id, credential.pat, text);
+      if (options.json) {
+        process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+        return;
+      }
+      process.stdout.write(`Added comment #${result.commentId} to work item #${result.workItemId}
+`);
+    } catch (err) {
+      handleCommandError(err, id, context, "write");
+    }
+  });
+  return command;
+}
+function createCommentsCommand() {
+  const command = new Command12("comments");
+  command.description("Manage Azure DevOps work item comments");
+  command.addCommand(createCommentsListCommand());
+  command.addCommand(createCommentsAddCommand());
+  return command;
+}
+
 // src/index.ts
-var program = new Command12();
+var program = new Command13();
 program.name("azdo").description("Azure DevOps CLI tool").version(version, "-v, --version");
 program.addCommand(createGetItemCommand());
 program.addCommand(createClearPatCommand());
@@ -1865,6 +2060,7 @@ program.addCommand(createSetMdFieldCommand());
 program.addCommand(createUpsertCommand());
 program.addCommand(createListFieldsCommand());
 program.addCommand(createPrCommand());
+program.addCommand(createCommentsCommand());
 program.showHelpAfterError();
 program.parse();
 if (process.argv.length <= 2) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "azdo-cli",
-  "version": "0.4.0",
+  "version": "0.5.0-010-work-item-comments.149",
   "description": "Azure DevOps CLI tool",
   "type": "module",
   "bin": {
@@ -15,7 +15,8 @@
     "typecheck": "tsc --noEmit",
     "format": "prettier --check src/",
     "test": "npm run build && vitest run tests/unit",
-    "test:integration": "npm run build && vitest run tests/integration"
+    "test:integration": "npm run build && vitest run tests/integration",
+    "test:integration:full": "bash scripts/setup-keyring.sh && npm run test:integration"
   },
   "repository": {
     "type": "git",