azdo-cli 0.19.0-develop.691 → 0.19.0-develop.710

package/README.md

@@ -15,7 +15,8 @@ Azure DevOps CLI focused on work item read/write workflows.
 - Attach a local file to a work item, or remove a named attachment (`add-attachment`, `delete-attachment`)
 - Read/write rich-text fields as markdown (`get-md-field`, `set-md-field`)
 - Download images embedded in rich-text fields, optionally resized for LLM use (`get-item`/`get-md-field` `--download-images`, `--resize-images`)
-- Check branch pull request status, open PRs to `develop` (optionally pre-filled from a repository-defined template), list PR comment threads for any PR (`--pr-number`), resolve/reopen threads, link/unlink work items, and add/remove required or optional reviewers — all from the CLI (`pr`)
+- Check branch pull request status, open PRs to `develop` (optionally pre-filled from a repository-defined template), update an existing PR's title or description (`pr update`), list PR comment threads for any PR (`--pr-number`), resolve/reopen threads, link/unlink work items, and add/remove required or optional reviewers — all from the CLI (`pr`)
+- Feed long PR titles, descriptions and comment bodies from a file or a pipe instead of the shell (`--title-file`, `--description-file`, `--file`; `-` reads standard input)
 - Persist org/project/default fields in local config (`config`)
 - List all fields of a work item (`list-fields`)
 - Authenticate per Azure DevOps organization with `azdo auth login` — OAuth (Microsoft Entra) by default, or a Personal Access Token via `--use-pat` (or the `AZDO_PAT` env var). Credentials are stored in the OS credential store. Inspect with `azdo auth status`, remove with `azdo auth logout`. Diagnose auth problems with `azdo auth diagnose`. See [docs/authentication.md](docs/authentication.md).
@@ -85,10 +86,21 @@ azdo pr comments edit 148 --file plan.md --pr-number 64        # rewrite it in p
 azdo pr comments reply 148 "Great suggestion, I'll address it."          # human-readable output
 azdo pr comments reply 148 "Done." --pr-number 64 --json                 # JSON: { pullRequestId, threadId, commentId, content }
 azdo pr comment-reply 148 "Done."  --pr-number 64                        # flat alias, identical behaviour
+git log -1 --format=%B | azdo pr comments add --file - --pr-number 64      # "-" reads standard input
 
 # Open a pull request — description from a repo template when you don't pass one
 azdo pr open --title "Fix the thing" --description "Because X was broken"
 azdo pr open --title "Fix the thing"   # uses docs/pull_request_template[/branches/<branch>].md if present
+azdo pr open --title "Fix the thing" --description-file body.md   # or --description-file - to pipe it in
+# The description plus the template must stay within Azure DevOps' 4000-character cap; over it,
+# the command says by how much and creates nothing. See docs/commands.md.
+
+# Fix a title or description after the fact — a PR is no longer write-once
+azdo pr update --pr-number 64 --title "A real title"        # description untouched
+azdo pr update --pr-number 64 --description-file body.md    # replaces literally; no template is prepended
+cat body.md | azdo pr edit --pr-number 64 --description-file -   # "edit" is an alias for "update"
+azdo pr update --pr-number 64 --title "A real title" --json  # { pullRequestId, title, description, url, noop, updatedFields }
+# Re-running with the values it already has writes nothing and reports "noop": true.
 
 # Link/unlink a work item, add/remove reviewers
 azdo pr work-items link 1234 --pr-number 64

package/dist/index.js

@@ -78,6 +78,21 @@ function redactUrl(url) {
     return url;
   }
 }
+var SECRET_ASSIGNMENT = String.raw`["']?\s*[:=]\s*["']?)[^"'\s,;&}]+`;
+var SECRET_IN_TEXT = [
+  [/\b(Bearer|Basic)\s+[\w.~+/=-]{8,}/gi, `$1 ${REDACTED}`],
+  [new RegExp(String.raw`(\b(?:access|refresh|api)[_-]?(?:token|key)\b${SECRET_ASSIGNMENT}`, "gi"), `$1${REDACTED}`],
+  [new RegExp(String.raw`(\b(?:token|pat|password|secret)\b${SECRET_ASSIGNMENT}`, "gi"), `$1${REDACTED}`],
+  [/\beyJ[A-Za-z0-9._~+/=-]{20,}/g, REDACTED],
+  [/\b(?=[A-Za-z0-9]*\d)(?=[A-Za-z0-9]*[A-Za-z])[A-Za-z0-9]{40,}\b/g, REDACTED]
+];
+function redactText(text) {
+  let out = text;
+  for (const [pattern, replacement] of SECRET_IN_TEXT) {
+    out = out.replace(pattern, replacement);
+  }
+  return out;
+}
 function redactBody(body) {
   if (body === null) return null;
   try {
@@ -123,6 +138,131 @@ function getActiveTraceWriter() {
   return activeWriter;
 }
 
+// src/services/command-helpers.ts
+function isSentinel(message, sentinel) {
+  return message === sentinel || message.startsWith(`${sentinel}: `);
+}
+function withDetail(sentinel, detail) {
+  return detail === null || detail === "" ? sentinel : `${sentinel}: ${detail}`;
+}
+function sentinelDetail(message, sentinel) {
+  return message.startsWith(`${sentinel}: `) ? message.slice(sentinel.length + 2) : null;
+}
+function splitSentinel(message) {
+  const separator = message.indexOf(": ");
+  return separator === -1 ? { sentinel: message, detail: null } : { sentinel: message.slice(0, separator), detail: message.slice(separator + 2) };
+}
+function writeErrorDetail(message, sentinel) {
+  const detail = sentinelDetail(message, sentinel);
+  if (detail !== null) {
+    process.stderr.write(`  ${detail}
+`);
+  }
+}
+async function promptYesNo(prompt) {
+  if (!process.stdin.isTTY) return true;
+  process.stderr.write(prompt);
+  return await new Promise((resolve2) => {
+    process.stdin.setEncoding("utf8");
+    let answered = false;
+    const handler = (data) => {
+      if (answered) return;
+      answered = true;
+      process.stdin.removeListener("data", handler);
+      process.stdin.pause();
+      const trimmed = data.trim().toLowerCase();
+      resolve2(trimmed === "y" || trimmed === "yes");
+    };
+    process.stdin.resume();
+    process.stdin.on("data", handler);
+  });
+}
+function parseWorkItemId(idStr) {
+  const id = Number.parseInt(idStr, 10);
+  if (!Number.isInteger(id) || id <= 0) {
+    process.stderr.write(
+      `Error: Work item ID must be a positive integer. Got: "${idStr}"
+`
+    );
+    process.exit(1);
+  }
+  return id;
+}
+function validateOrgProjectPair(options) {
+  const hasOrg = options.org !== void 0;
+  const hasProject = options.project !== void 0;
+  if (hasOrg !== hasProject) {
+    process.stderr.write(
+      "Error: --org and --project must both be provided, or both omitted.\n"
+    );
+    process.exit(1);
+  }
+}
+function validateSource(options) {
+  const hasContent = options.content !== void 0;
+  const hasFile = options.file !== void 0;
+  if (hasContent === hasFile) {
+    process.stderr.write("Error: provide exactly one of --content or --file\n");
+    process.exit(1);
+  }
+}
+function formatCreateError(err) {
+  const error = err instanceof Error ? err : new Error(String(err));
+  const message = error.message.startsWith("CREATE_REJECTED:") ? error.message.replace("CREATE_REJECTED:", "").trim() : error.message;
+  const requiredMatches = [...message.matchAll(/field ['"]([^'"]+)['"]/gi)];
+  if (requiredMatches.length > 0) {
+    const fields = Array.from(new Set(requiredMatches.map((match) => match[1])));
+    return `Create rejected: ${message} (fields: ${fields.join(", ")})`;
+  }
+  return `Create rejected: ${message}`;
+}
+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)";
+  if (isSentinel(msg, "AUTH_FAILED")) {
+    process.stderr.write(
+      `Error: Authentication failed. Check that your PAT is valid and has the "${scopeLabel}" scope.
+`
+    );
+    writeErrorDetail(msg, "AUTH_FAILED");
+  } else if (isSentinel(msg, "PERMISSION_DENIED")) {
+    process.stderr.write(
+      `Error: Access denied. Your PAT may lack ${scope} permissions for project "${context?.project}".
+`
+    );
+    writeErrorDetail(msg, "PERMISSION_DENIED");
+  } else if (msg.startsWith("NOT_FOUND")) {
+    process.stderr.write(
+      `Error: Work item ${id} not found in ${context?.org}/${context?.project}.
+`
+    );
+  } else if (msg === "NETWORK_ERROR") {
+    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("CREATE_REJECTED:")) {
+    process.stderr.write(`Error: ${formatCreateError(error)}
+`);
+  } else if (msg.startsWith("UPDATE_REJECTED:")) {
+    const serverMsg = msg.replace("UPDATE_REJECTED: ", "");
+    process.stderr.write(`Error: Update rejected: ${serverMsg}
+`);
+  } else {
+    process.stderr.write(`Error: ${msg}
+`);
+  }
+  if (exit) {
+    process.exit(1);
+  } else {
+    process.exitCode = 1;
+  }
+}
+
 // src/services/image-download.ts
 import { Jimp } from "jimp";
 import { writeFile } from "fs/promises";
@@ -326,65 +466,136 @@ async function fetchRaw(url, init) {
   const body = await response.text();
   return { status: response.status, body };
 }
-async function fetchWithErrors(url, init) {
+var MAX_DETAIL_CHARS = 500;
+var MAX_RAW_BODY_CHARS = 200;
+var failureDetails = /* @__PURE__ */ new WeakMap();
+function renderErrorFields(body, requireMessage = false) {
+  let parsed;
+  try {
+    parsed = JSON.parse(body);
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null) return null;
+  return renderErrorRecord(parsed, requireMessage);
+}
+function renderErrorRecord(record, requireMessage) {
+  const parts = [];
+  const message = typeof record.message === "string" ? record.message.trim() : "";
+  if (message !== "") {
+    parts.push(message);
+  } else if (requireMessage) {
+    return null;
+  }
+  if (typeof record.typeKey === "string" && record.typeKey.trim() !== "") {
+    parts.push(`[${record.typeKey.trim()}]`);
+  } else if (typeof record.errorCode === "number" || typeof record.errorCode === "string") {
+    parts.push(`[errorCode ${record.errorCode}]`);
+  }
+  return parts.length === 0 ? null : parts.join(" ");
+}
+function describeFailureBody(body, contentType) {
+  if (body === null) return null;
+  const trimmed = body.trim();
+  if (trimmed === "") return null;
+  if (contentType.toLowerCase().startsWith("text/html") || trimmed.startsWith("<")) {
+    return null;
+  }
+  const redacted = redactBody(trimmed) ?? trimmed;
+  const fields = renderErrorFields(redacted);
+  if (fields !== null) return truncateDetail(fields);
+  return truncateDetail(redactText(redacted).slice(0, MAX_RAW_BODY_CHARS));
+}
+function truncateDetail(detail) {
+  const collapsed = redactText(detail).replace(/\s+/g, " ").trim();
+  if (collapsed === "") return null;
+  return collapsed.length > MAX_DETAIL_CHARS ? `${collapsed.slice(0, MAX_DETAIL_CHARS)}\u2026(truncated)` : collapsed;
+}
+function httpError(response) {
+  return new Error(withDetail(`HTTP_${response.status}`, failureDetails.get(response) ?? null));
+}
+var failureBodies = /* @__PURE__ */ new WeakMap();
+async function readFailureBody(response, tracedBody) {
+  if (tracedBody !== null) return tracedBody;
+  try {
+    return await response.clone().text();
+  } catch {
+    try {
+      return await response.text();
+    } catch {
+      return null;
+    }
+  }
+}
+function writeTraceEntry(writer, url, init, response, responseBody) {
+  const respHeaders = {};
+  response.headers.forEach((v, k) => {
+    respHeaders[k] = v;
+  });
+  const entry = {
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    method: (init.method ?? "GET").toUpperCase(),
+    url: redactUrl(url),
+    requestHeaders: redactHeaders(init.headers ?? {}),
+    requestBody: typeof init.body === "string" ? redactBody(init.body) : null,
+    responseStatus: response.status,
+    responseHeaders: respHeaders,
+    responseBody
+  };
+  writer.append(entry);
+}
+async function traceResponse(url, init, response) {
   const writer = getActiveTraceWriter();
+  if (!writer) return null;
+  let responseBody = null;
+  try {
+    responseBody = await response.clone().text();
+  } catch {
+  }
+  writeTraceEntry(writer, url, init, response, responseBody ?? "");
+  return responseBody;
+}
+async function fetchWithErrors(url, init) {
   let response;
   try {
     response = await fetch(url, init);
   } catch (err) {
     throw new Error("NETWORK_ERROR", { cause: err });
   }
-  if (writer) {
-    const reqHeaders = redactHeaders(init.headers ?? {});
-    const reqBody = typeof init.body === "string" ? redactBody(init.body) : null;
-    let responseBody = "";
-    const clone = response.clone();
-    try {
-      responseBody = await clone.text();
-    } catch {
-    }
-    const respHeaders = {};
-    response.headers.forEach((v, k) => {
-      respHeaders[k] = v;
-    });
-    const entry = {
-      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-      method: (init.method ?? "GET").toUpperCase(),
-      url: redactUrl(url),
-      requestHeaders: reqHeaders,
-      requestBody: reqBody ?? null,
-      responseStatus: response.status,
-      responseHeaders: respHeaders,
-      responseBody
-    };
-    writer.append(entry);
+  const tracedBody = await traceResponse(url, init, response);
+  const contentType = response.headers?.get("content-type") ?? "";
+  let failureDetail = null;
+  if (!response.ok) {
+    const body = await readFailureBody(response, tracedBody);
+    if (body !== null) failureBodies.set(response, body);
+    failureDetail = describeFailureBody(body, contentType);
+    if (failureDetail !== null) failureDetails.set(response, failureDetail);
   }
-  if (response.status === 401) throw new Error("AUTH_FAILED");
-  if (response.status === 403) throw new Error("PERMISSION_DENIED");
+  if (response.status === 401) throw new Error(withDetail("AUTH_FAILED", failureDetail));
+  if (response.status === 403) throw new Error(withDetail("PERMISSION_DENIED", failureDetail));
   if (response.status === 404) {
-    let detail = "";
-    try {
-      const body = await response.text();
-      detail = ` | url=${url} | body=${body}`;
-    } catch {
-    }
-    throw new Error(`NOT_FOUND${detail}`);
+    throw new Error(
+      failureDetail === null ? "NOT_FOUND" : `NOT_FOUND | url=${redactUrl(url)} | body=${failureDetail}`
+    );
   }
-  const contentType = response.headers?.get("content-type") ?? "";
   if (contentType.toLowerCase().startsWith("text/html")) {
     throw new Error("AUTH_FAILED");
   }
   return response;
 }
 async function readResponseMessage(response) {
+  const captured = failureBodies.get(response);
+  const rendered = captured === void 0 ? await renderErrorStream(response) : renderErrorFields(redactBody(captured.trim()) ?? captured.trim(), true);
+  return rendered === null ? null : truncateDetail(rendered);
+}
+async function renderErrorStream(response) {
   try {
     const body = await response.json();
-    if (typeof body.message === "string" && body.message.trim() !== "") {
-      return body.message.trim();
-    }
+    if (typeof body !== "object" || body === null) return null;
+    return renderErrorRecord(body, true);
   } catch {
+    return null;
   }
-  return null;
 }
 function normalizeFieldList(fields) {
   return Array.from(new Set(fields.map((f) => f.trim()).filter((f) => f.length > 0)));
@@ -464,7 +675,7 @@ async function readWriteResponse(response, errorCode) {
     throw new Error(`${errorCode}: ${serverMessage}`);
   }
   if (!response.ok) {
-    throw new Error(`HTTP_${response.status}`);
+    throw httpError(response);
   }
   const data = await response.json();
   return {
@@ -487,7 +698,7 @@ async function getWorkItemFields(context, id, cred) {
     }
   }
   if (!response.ok) {
-    throw new Error(`HTTP_${response.status}`);
+    throw httpError(response);
   }
   const data = await response.json();
   return data.fields;
@@ -539,7 +750,7 @@ async function fetchWorkItemResponse(context, id, cred, options = {}) {
     }
   }
   if (!response.ok) {
-    throw new Error(`HTTP_${response.status}`);
+    throw httpError(response);
   }
   return await response.json();
 }
@@ -550,7 +761,7 @@ async function getOrgFieldNames(context, cred) {
   url.searchParams.set("api-version", "7.1");
   const response = await fetchWithErrors(url.toString(), { headers: authHeaders(cred) });
   if (!response.ok) {
-    throw new Error(`HTTP_${response.status}`);
+    throw httpError(response);
   }
   const data = await response.json();
   return (data.value ?? []).map((f) => f.referenceName);
@@ -632,7 +843,7 @@ async function getWorkItemFieldValue(context, id, cred, fieldName) {
     }
   }
   if (!response.ok) {
-    throw new Error(`HTTP_${response.status}`);
+    throw httpError(response);
   }
   const data = await response.json();
   const value = data.fields[fieldName];
@@ -650,7 +861,7 @@ async function listWorkItemComments(context, id, cred) {
       { headers: authHeaders(cred) }
     );
     if (!response.ok) {
-      throw new Error(`HTTP_${response.status}`);
+      throw httpError(response);
     }
     const data = await response.json();
     comments.push(
@@ -680,7 +891,7 @@ async function addWorkItemComment(context, id, cred, text, format = "html") {
     throw new Error(`BAD_REQUEST: ${serverMessage}`);
   }
   if (!response.ok) {
-    throw new Error(`HTTP_${response.status}`);
+    throw httpError(response);
   }
   const data = await response.json();
   return {
@@ -732,7 +943,7 @@ async function applyWorkItemPatch(context, id, cred, operations) {
 async function downloadAttachment(url, cred) {
   const response = await fetchWithErrors(url, { headers: authHeaders(cred) });
   if (!response.ok) {
-    throw new Error(`HTTP_${response.status}`);
+    throw httpError(response);
   }
   return response.arrayBuffer();
 }
@@ -757,7 +968,7 @@ async function createAttachment(context, fileName, content, cred) {
     }
   }
   if (!response.ok) {
-    throw new Error(`HTTP_${response.status}`);
+    throw httpError(response);
   }
   return await response.json();
 }
@@ -1546,109 +1757,6 @@ function toMarkdown(content) {
   return decodeEntitiesInMarkdownCodeSpans(decodeAdoEntitiesInMarkdown(content));
 }
 
-// src/services/command-helpers.ts
-async function promptYesNo(prompt) {
-  if (!process.stdin.isTTY) return true;
-  process.stderr.write(prompt);
-  return await new Promise((resolve2) => {
-    process.stdin.setEncoding("utf8");
-    let answered = false;
-    const handler = (data) => {
-      if (answered) return;
-      answered = true;
-      process.stdin.removeListener("data", handler);
-      process.stdin.pause();
-      const trimmed = data.trim().toLowerCase();
-      resolve2(trimmed === "y" || trimmed === "yes");
-    };
-    process.stdin.resume();
-    process.stdin.on("data", handler);
-  });
-}
-function parseWorkItemId(idStr) {
-  const id = Number.parseInt(idStr, 10);
-  if (!Number.isInteger(id) || id <= 0) {
-    process.stderr.write(
-      `Error: Work item ID must be a positive integer. Got: "${idStr}"
-`
-    );
-    process.exit(1);
-  }
-  return id;
-}
-function validateOrgProjectPair(options) {
-  const hasOrg = options.org !== void 0;
-  const hasProject = options.project !== void 0;
-  if (hasOrg !== hasProject) {
-    process.stderr.write(
-      "Error: --org and --project must both be provided, or both omitted.\n"
-    );
-    process.exit(1);
-  }
-}
-function validateSource(options) {
-  const hasContent = options.content !== void 0;
-  const hasFile = options.file !== void 0;
-  if (hasContent === hasFile) {
-    process.stderr.write("Error: provide exactly one of --content or --file\n");
-    process.exit(1);
-  }
-}
-function formatCreateError(err) {
-  const error = err instanceof Error ? err : new Error(String(err));
-  const message = error.message.startsWith("CREATE_REJECTED:") ? error.message.replace("CREATE_REJECTED:", "").trim() : error.message;
-  const requiredMatches = [...message.matchAll(/field ['"]([^'"]+)['"]/gi)];
-  if (requiredMatches.length > 0) {
-    const fields = Array.from(new Set(requiredMatches.map((match) => match[1])));
-    return `Create rejected: ${message} (fields: ${fields.join(", ")})`;
-  }
-  return `Create rejected: ${message}`;
-}
-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)";
-  if (msg === "AUTH_FAILED") {
-    process.stderr.write(
-      `Error: Authentication failed. Check that your PAT is valid and has the "${scopeLabel}" scope.
-`
-    );
-  } else if (msg === "PERMISSION_DENIED") {
-    process.stderr.write(
-      `Error: Access denied. Your PAT may lack ${scope} permissions for project "${context?.project}".
-`
-    );
-  } else if (msg.startsWith("NOT_FOUND")) {
-    process.stderr.write(
-      `Error: Work item ${id} not found in ${context?.org}/${context?.project}.
-`
-    );
-  } else if (msg === "NETWORK_ERROR") {
-    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("CREATE_REJECTED:")) {
-    process.stderr.write(`Error: ${formatCreateError(error)}
-`);
-  } else if (msg.startsWith("UPDATE_REJECTED:")) {
-    const serverMsg = msg.replace("UPDATE_REJECTED: ", "");
-    process.stderr.write(`Error: Update rejected: ${serverMsg}
-`);
-  } else {
-    process.stderr.write(`Error: ${msg}
-`);
-  }
-  if (exit) {
-    process.exit(1);
-  } else {
-    process.exitCode = 1;
-  }
-}
-
 // src/commands/get-item.ts
 function parseRequestedFields(raw) {
   if (raw === void 0) return void 0;
@@ -3132,10 +3240,10 @@ function buildUpsertResult(action, writeResult, fields, fallbackWorkItemType) {
   };
 }
 function isUpdateWriteError(err) {
-  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:");
+  return isSentinel(err.message, "AUTH_FAILED") || isSentinel(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_");
+  return isSentinel(err.message, "AUTH_FAILED") || isSentinel(err.message, "PERMISSION_DENIED") || err.message === "NETWORK_ERROR" || err.message.startsWith("BAD_REQUEST:") || err.message.startsWith("HTTP_");
 }
 function handleUpsertError(err, id, context) {
   if (!(err instanceof Error)) {
@@ -3465,7 +3573,7 @@ function isThreadResolved(status2) {
 }
 async function readJsonResponse(response) {
   if (!response.ok) {
-    throw new Error(`HTTP_${response.status}`);
+    throw httpError(response);
   }
   return response.json();
 }
@@ -3552,19 +3660,35 @@ async function getPullRequestBuilds(context, cred, prId) {
     isBlocking: null
   }));
 }
+var MAX_PR_DESCRIPTION_CHARS = 4e3;
+var DESCRIPTION_SEPARATOR = "\n\n";
 function composeDescription(description, template) {
-  if (description !== void 0 && template !== null) {
-    return `${description}
-
-${template.content}`;
-  }
-  if (description !== void 0) {
-    return description;
-  }
-  if (template !== null) {
-    return template.content;
+  if (description === void 0 && template === null) {
+    return null;
   }
-  return null;
+  const provided = description ?? "";
+  const templateContent = template?.content ?? "";
+  const separator = description !== void 0 && template !== null ? DESCRIPTION_SEPARATOR : "";
+  const text = `${provided}${separator}${templateContent}`;
+  return {
+    text,
+    providedChars: provided.length,
+    separatorChars: separator.length,
+    templateChars: templateContent.length,
+    templatePath: template?.path ?? null,
+    totalChars: text.length
+  };
+}
+function formatDescriptionOverflow(composed) {
+  const overflow = composed.totalChars - MAX_PR_DESCRIPTION_CHARS;
+  return `description is ${composed.totalChars} characters${formatContributions(composed)}, exceeding the Azure DevOps limit of ${MAX_PR_DESCRIPTION_CHARS} characters. Shorten the description by at least ${overflow} characters.`;
+}
+function formatContributions(composed) {
+  if (composed.templatePath === null) return "";
+  return ` (${composed.providedChars} provided + ${composed.separatorChars} separator + ${composed.templateChars} from the repository pull request template ${composed.templatePath})`;
+}
+function describeDescriptionBudget(composed) {
+  return `description: ${composed.providedChars} provided + ${composed.separatorChars} separator + ${composed.templateChars} template = ${composed.totalChars} characters (client limit ${MAX_PR_DESCRIPTION_CHARS})`;
 }
 async function openPullRequest(context, repo, cred, sourceBranch, title, description) {
   const existing = await listPullRequests(context, repo, cred, sourceBranch, {
@@ -3585,35 +3709,68 @@ async function openPullRequest(context, repo, cred, sourceBranch, title, descrip
   const repository = await getRepository(context, repo, cred);
   const defaultBranch = repository.defaultBranch ? repository.defaultBranch.replace(/^refs\/heads\//, "") : "develop";
   const template = await resolvePullRequestTemplate(context, repo, cred, defaultBranch, "develop");
-  const finalDescription = composeDescription(description, template);
-  if (finalDescription === null) {
+  const composed = composeDescription(description, template);
+  if (composed === null) {
     throw new Error("DESCRIPTION_REQUIRED");
   }
+  if (composed.totalChars > MAX_PR_DESCRIPTION_CHARS) {
+    throw new Error(`DESCRIPTION_TOO_LONG: ${formatDescriptionOverflow(composed)}`);
+  }
   const payload = {
     sourceRefName: `refs/heads/${sourceBranch}`,
     targetRefName: "refs/heads/develop",
     title,
-    description: finalDescription
+    description: composed.text
   };
   const url = new URL(
     `https://dev.azure.com/${encodeURIComponent(context.org)}/${encodeURIComponent(context.project)}/_apis/git/repositories/${encodeURIComponent(repo)}/pullrequests`
   );
   url.searchParams.set("api-version", "7.1");
+  let data;
+  try {
+    const response = await fetchWithErrors(url.toString(), {
+      method: "POST",
+      headers: {
+        ...authHeaders(cred),
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(payload)
+    });
+    data = await readJsonResponse(response);
+  } catch (err) {
+    if (err instanceof Error && err.message.startsWith("HTTP_400")) {
+      throw new Error(`${err.message} | ${describeDescriptionBudget(composed)}`, { cause: err });
+    }
+    throw err;
+  }
+  return {
+    branch: sourceBranch,
+    targetBranch: "develop",
+    created: true,
+    pullRequest: mapPullRequest(context, repo, data)
+  };
+}
+async function updatePullRequest(context, repo, cred, prId, fields) {
+  if (fields.description !== void 0 && fields.description.length > MAX_PR_DESCRIPTION_CHARS) {
+    const overflow = fields.description.length - MAX_PR_DESCRIPTION_CHARS;
+    throw new Error(
+      `DESCRIPTION_TOO_LONG: description is ${fields.description.length} characters, exceeding the Azure DevOps limit of ${MAX_PR_DESCRIPTION_CHARS} characters. Shorten the description by at least ${overflow} characters.`
+    );
+  }
+  const url = new URL(
+    `https://dev.azure.com/${encodeURIComponent(context.org)}/${encodeURIComponent(context.project)}/_apis/git/repositories/${encodeURIComponent(repo)}/pullrequests/${prId}`
+  );
+  url.searchParams.set("api-version", "7.1");
   const response = await fetchWithErrors(url.toString(), {
-    method: "POST",
+    method: "PATCH",
     headers: {
       ...authHeaders(cred),
       "Content-Type": "application/json"
     },
-    body: JSON.stringify(payload)
+    body: JSON.stringify(fields)
   });
   const data = await readJsonResponse(response);
-  return {
-    branch: sourceBranch,
-    targetBranch: "develop",
-    created: true,
-    pullRequest: mapPullRequest(context, repo, data)
-  };
+  return mapPullRequest(context, repo, data);
 }
 async function getPullRequestThreads(context, repo, cred, prId) {
   const url = new URL(
@@ -3745,7 +3902,7 @@ async function patchWorkItemRelations(context, cred, workItemId, operation) {
     body: JSON.stringify([operation])
   });
   if (!response.ok) {
-    throw new Error(`HTTP_${response.status}`);
+    throw httpError(response);
   }
 }
 async function linkWorkItemToPullRequest(context, repo, cred, prId, workItemId) {
@@ -3794,8 +3951,8 @@ async function resolveReviewerIdentity(org, cred, input) {
       headers: authHeaders(cred)
     });
   } catch (err) {
-    if (err instanceof Error && err.message === "AUTH_FAILED") {
-      throw new Error("IDENTITY_SCOPE_MISSING", { cause: err });
+    if (err instanceof Error && isSentinel(err.message, "AUTH_FAILED")) {
+      throw new Error(withDetail("IDENTITY_SCOPE_MISSING", sentinelDetail(err.message, "AUTH_FAILED")), { cause: err });
     }
     throw err;
   }
@@ -3853,7 +4010,7 @@ async function removePullRequestReviewer(context, repo, cred, prId, reviewerId)
     headers: authHeaders(cred)
   });
   if (!response.ok) {
-    throw new Error(`HTTP_${response.status}`);
+    throw httpError(response);
   }
   return { reviewer: existing, noop: false };
 }
@@ -3892,7 +4049,7 @@ async function fetchRepositoryItemContent(context, repo, cred, path3, branch) {
     throw err;
   }
   if (!response.ok) {
-    throw new Error(`HTTP_${response.status}`);
+    throw httpError(response);
   }
   return response.text();
 }
@@ -3972,6 +4129,27 @@ function writeContractError(line) {
   process.exitCode = 1;
 }
 var EMPTY_BODY_ERROR = "Comment text must not be empty. Pass the text inline or use --file <path>.";
+var STDIN_PATH = "-";
+function readTextSource(file) {
+  if (file === STDIN_PATH) {
+    try {
+      return readFileSync5(0, "utf-8");
+    } catch {
+      writeError("Cannot read standard input.");
+      return null;
+    }
+  }
+  if (!existsSync5(file)) {
+    writeError(`File not found: ${file}`);
+    return null;
+  }
+  try {
+    return readFileSync5(file, "utf-8");
+  } catch {
+    writeError(`Cannot read file: ${file}`);
+    return null;
+  }
+}
 function resolveCommentBody(inline, file, emptyMessage = EMPTY_BODY_ERROR) {
   if (inline !== void 0 && file !== void 0) {
     writeError("Cannot specify both inline text and --file.");
@@ -3979,16 +4157,11 @@ function resolveCommentBody(inline, file, emptyMessage = EMPTY_BODY_ERROR) {
   }
   let body;
   if (file !== void 0) {
-    if (!existsSync5(file)) {
-      writeError(`File not found: ${file}`);
-      return null;
-    }
-    try {
-      body = readFileSync5(file, "utf-8");
-    } catch {
-      writeError(`Cannot read file: ${file}`);
+    const read = readTextSource(file);
+    if (read === null) {
       return null;
     }
+    body = read;
   } else if (inline !== void 0) {
     body = inline;
   } else {
@@ -4002,6 +4175,33 @@ function resolveCommentBody(inline, file, emptyMessage = EMPTY_BODY_ERROR) {
   }
   return trimmed;
 }
+function resolveOptionalTextInput(inline, file, flag) {
+  if (inline !== void 0 && file !== void 0) {
+    writeError(`Cannot specify both --${flag} and --${flag}-file.`);
+    return null;
+  }
+  if (inline === void 0 && file === void 0) {
+    return void 0;
+  }
+  const label = flag === "title" ? "Title" : "Description";
+  const emptyMessage = `${label} must not be empty. Pass the text inline or use --${flag}-file <path>.`;
+  let value;
+  if (file !== void 0) {
+    const read = readTextSource(file);
+    if (read === null) {
+      return null;
+    }
+    value = read;
+  } else {
+    value = inline;
+  }
+  const trimmed = value.trim();
+  if (trimmed === "") {
+    writeError(emptyMessage);
+    return null;
+  }
+  return trimmed;
+}
 function parseNonNegativeInt(raw) {
   if (!/^\d+$/.test(raw)) {
     return null;
@@ -4027,7 +4227,7 @@ function writeError(message, exitCode = 1) {
 }
 function handlePrCommandError(err, context, mode = "read") {
   const error = err instanceof Error ? err : new Error(String(err));
-  if (error.message === "AUTH_FAILED") {
+  if (isSentinel(error.message, "AUTH_FAILED")) {
     const scopeLabel = mode === "write" ? "Code (Read & Write)" : "Code (Read)";
     writeError(`Authentication failed. Check that your PAT is valid and has the "${scopeLabel}" scope.`, EXIT_NOT_PERMITTED);
     const credentialHint = describeResolvedCredential();
@@ -4035,17 +4235,20 @@ function handlePrCommandError(err, context, mode = "read") {
       process.stderr.write(`  ${credentialHint}
 `);
     }
+    writeErrorDetail(error.message, "AUTH_FAILED");
     return;
   }
-  if (error.message === "IDENTITY_SCOPE_MISSING") {
+  if (isSentinel(error.message, "IDENTITY_SCOPE_MISSING")) {
     writeError(
       'Could not resolve reviewer identity: your PAT is missing the "Identity (Read)" scope required by the Azure DevOps identities API (separate from Code scope).',
       EXIT_NOT_PERMITTED
     );
+    writeErrorDetail(error.message, "IDENTITY_SCOPE_MISSING");
     return;
   }
-  if (error.message === "PERMISSION_DENIED") {
+  if (isSentinel(error.message, "PERMISSION_DENIED")) {
     writeError(`Access denied. Your PAT may lack ${mode} permissions for project "${context?.project}".`, EXIT_NOT_PERMITTED);
+    writeErrorDetail(error.message, "PERMISSION_DENIED");
     return;
   }
   if (error.message === "NETWORK_ERROR") {
@@ -4057,7 +4260,12 @@ function handlePrCommandError(err, context, mode = "read") {
     return;
   }
   if (error.message.startsWith("HTTP_")) {
-    writeError(`Azure DevOps request failed with ${error.message}.`);
+    const { sentinel, detail } = splitSentinel(error.message);
+    writeError(`Azure DevOps request failed with ${sentinel}.`);
+    if (detail !== null) {
+      process.stderr.write(`  ${detail}
+`);
+    }
     return;
   }
   writeError(error.message);
@@ -4232,11 +4440,54 @@ function createPrStatusCommand() {
   });
   return command;
 }
+function handlePrOpenError(err, context) {
+  const message = err instanceof Error ? err.message : "";
+  if (message.startsWith("AMBIGUOUS_PRS:")) {
+    const ids = message.replace("AMBIGUOUS_PRS:", "").split(",").map((id) => `#${id}`).join(", ");
+    writeError(`Multiple active pull requests already exist for this branch targeting develop: ${ids}. Use pr status to review them.`);
+    return;
+  }
+  if (message === "DESCRIPTION_REQUIRED") {
+    writeError("--description is required for pull request creation.");
+    return;
+  }
+  if (message.startsWith("DESCRIPTION_TOO_LONG: ")) {
+    writeError(message.slice("DESCRIPTION_TOO_LONG: ".length));
+    return;
+  }
+  handlePrCommandError(err, context, "write");
+}
+function resolveOpenDescription(inline, file) {
+  if (inline !== void 0 && file !== void 0) {
+    writeError("Cannot specify both --description and --description-file.");
+    return null;
+  }
+  if (file !== void 0) {
+    const fromFile = readTextSource(file);
+    if (fromFile === null) {
+      return null;
+    }
+    const trimmed = fromFile.trim();
+    if (trimmed === "") {
+      writeError("Description must not be empty. Pass the text inline or use --description-file <path>.");
+      return null;
+    }
+    return trimmed;
+  }
+  const trimmedInline = inline?.trim();
+  if (trimmedInline === void 0 || trimmedInline === "") {
+    return void 0;
+  }
+  return trimmedInline;
+}
 function createPrOpenCommand() {
   const command = new Command12("open");
   withCommonPrOptions(command).description("Open a pull request from the current branch to develop").option("--title <title>", "pull request title").option(
     "--description <description>",
     "pull request description; when omitted, a repository-defined pull request template is used if one exists (prepended by this text when both are present)"
+  ).option(
+    "--description-file <path>",
+    'read the description from a UTF-8 file instead of --description; "-" reads standard input'
   ).option("--json", "output JSON").action(async (options) => {
     validateOrgProjectPair(options);
     const title = options.title?.trim();
@@ -4244,8 +4495,10 @@ function createPrOpenCommand() {
       writeError("--title is required for pull request creation.");
       return;
     }
-    const trimmedDescription = options.description?.trim();
-    const description = trimmedDescription && trimmedDescription.length > 0 ? trimmedDescription : void 0;
+    const description = resolveOpenDescription(options.description, options.descriptionFile);
+    if (description === null) {
+      return;
+    }
     let context;
     try {
       const resolved = await resolvePrCommandContext(options);
@@ -4280,17 +4533,125 @@ ${result.pullRequest.url ?? "\u2014"}
 `
       );
     } catch (err) {
-      if (err instanceof Error && err.message.startsWith("AMBIGUOUS_PRS:")) {
-        const ids = err.message.replace("AMBIGUOUS_PRS:", "").split(",").map((id) => `#${id}`).join(", ");
-        writeError(`Multiple active pull requests already exist for this branch targeting develop: ${ids}. Use pr status to review them.`);
-        return;
-      }
-      if (err instanceof Error && err.message === "DESCRIPTION_REQUIRED") {
-        writeError("--description is required for pull request creation.");
+      handlePrOpenError(err, context);
+    }
+  });
+  return command;
+}
+function handlePrUpdateError(err, context) {
+  const message = err instanceof Error ? err.message : "";
+  if (message.startsWith("DESCRIPTION_TOO_LONG: ")) {
+    writeError(message.slice("DESCRIPTION_TOO_LONG: ".length));
+    return;
+  }
+  handlePrCommandError(err, context, "write");
+}
+function joinFieldNames(fields) {
+  return fields.join(" and ");
+}
+function resolveRequestedFields(options) {
+  if (options.titleFile === STDIN_PATH && options.descriptionFile === STDIN_PATH) {
+    writeError('Cannot read standard input twice; only one of --title-file and --description-file may be "-".');
+    return null;
+  }
+  const title = resolveOptionalTextInput(options.title, options.titleFile, "title");
+  if (title === null) {
+    return null;
+  }
+  const description = resolveOptionalTextInput(options.description, options.descriptionFile, "description");
+  if (description === null) {
+    return null;
+  }
+  if (title === void 0 && description === void 0) {
+    writeError("pr update requires at least one of --title, --title-file, --description or --description-file.");
+    return null;
+  }
+  return { title, description };
+}
+function diffRequestedFields(requested, current) {
+  const fields = {};
+  const updatedFields = [];
+  const requestedFields = [];
+  if (requested.title !== void 0) {
+    requestedFields.push("title");
+    if (requested.title !== current.title) {
+      fields.title = requested.title;
+      updatedFields.push("title");
+    }
+  }
+  if (requested.description !== void 0) {
+    requestedFields.push("description");
+    if (requested.description !== (current.description ?? "")) {
+      fields.description = requested.description;
+      updatedFields.push("description");
+    }
+  }
+  return { fields, updatedFields, requestedFields };
+}
+async function runPrUpdate(options) {
+  const requested = resolveRequestedFields(options);
+  if (requested === null) {
+    return;
+  }
+  let context;
+  try {
+    const target = await resolvePullRequestTarget(options);
+    if (target === null) {
+      return;
+    }
+    context = target.context;
+    const current = target.pullRequest;
+    const { fields, updatedFields, requestedFields } = diffRequestedFields(requested, current);
+    if (updatedFields.length === 0) {
+      const noopResult = {
+        pullRequestId: current.id,
+        title: current.title,
+        description: current.description ?? null,
+        url: current.url,
+        noop: true,
+        updatedFields: []
+      };
+      if (options.json) {
+        process.stdout.write(`${JSON.stringify(noopResult, null, 2)}
+`);
         return;
       }
-      handlePrCommandError(err, context, "write");
+      process.stdout.write(
+        `Pull request #${current.id} already has the requested ${joinFieldNames(requestedFields)}; nothing to update.
+`
+      );
+      return;
+    }
+    const updated = await updatePullRequest(target.context, target.repo, target.pat, current.id, fields);
+    const result = {
+      pullRequestId: updated.id,
+      title: updated.title,
+      description: updated.description ?? null,
+      url: updated.url,
+      noop: false,
+      updatedFields
+    };
+    if (options.json) {
+      process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+      return;
     }
+    process.stdout.write(
+      `Updated pull request #${updated.id} (${updatedFields.join(", ")}).
+${updated.url ?? "\u2014"}
+`
+    );
+  } catch (err) {
+    handlePrUpdateError(err, context);
+  }
+}
+function createPrUpdateCommand() {
+  const command = new Command12("update");
+  withCommonPrOptions(configureUnwrappedHelp(command)).alias("edit").description("Update a pull request's title and/or description").option("--pr-number <N>", PR_NUMBER_HELP).option("--title <title>", "new pull request title").option("--title-file <path>", 'read the new title from a UTF-8 file; "-" reads standard input').option(
+    "--description <description>",
+    'new pull request description; REPLACES the existing description literally \u2014 no repository pull request template is looked up or prepended, unlike "azdo pr open"'
+  ).option("--description-file <path>", 'read the new description from a UTF-8 file; "-" reads standard input').option("--json", "output JSON").action(async (_options, command2) => {
+    await runPrUpdate(mergedPrOptions(command2));
   });
   return command;
 }
@@ -5073,6 +5434,7 @@ function createPrCommand() {
   command.addCommand(createPrListCommand());
   command.addCommand(createPrStatusCommand());
   command.addCommand(createPrOpenCommand());
+  command.addCommand(createPrUpdateCommand());
   command.addCommand(createPrCommentsCommand());
   command.addCommand(createPrCommentResolveCommand());
   command.addCommand(createPrCommentReopenCommand());
@@ -5098,7 +5460,7 @@ function withApiVersion(url) {
 }
 async function readJsonResponse2(response) {
   if (!response.ok) {
-    throw new Error(`HTTP_${response.status}`);
+    throw httpError(response);
   }
   return await response.json();
 }
@@ -5374,7 +5736,7 @@ async function getRunLog(context, cred, buildId, logId) {
   );
   const response = await fetchWithErrors(url.toString(), { headers: authHeaders(cred) });
   if (!response.ok) {
-    throw new Error(`HTTP_${response.status}`);
+    throw httpError(response);
   }
   return response.text();
 }
@@ -5390,12 +5752,14 @@ function writeError2(message) {
 }
 function handlePipelineError(err, context) {
   const error = err instanceof Error ? err : new Error(String(err));
-  if (error.message === "AUTH_FAILED") {
+  if (isSentinel(error.message, "AUTH_FAILED")) {
     writeError2('Authentication failed. Check that your credential is valid and has the "Build (Read)" scope.');
+    writeErrorDetail(error.message, "AUTH_FAILED");
     return;
   }
-  if (error.message === "PERMISSION_DENIED") {
+  if (isSentinel(error.message, "PERMISSION_DENIED")) {
     writeError2(`Access denied. Your credential may lack pipeline permissions for project "${context?.project}".`);
+    writeErrorDetail(error.message, "PERMISSION_DENIED");
     return;
   }
   if (error.message === "NETWORK_ERROR") {
@@ -5407,7 +5771,12 @@ function handlePipelineError(err, context) {
     return;
   }
   if (error.message.startsWith("HTTP_")) {
-    writeError2(`Azure DevOps request failed with ${error.message}.`);
+    const { sentinel, detail } = splitSentinel(error.message);
+    writeError2(`Azure DevOps request failed with ${sentinel}.`);
+    if (detail !== null) {
+      process.stderr.write(`  ${detail}
+`);
+    }
     return;
   }
   writeError2(error.message);
@@ -6299,7 +6668,7 @@ function mapRelationType(raw) {
   };
 }
 async function readJsonResponse3(response) {
-  if (!response.ok) throw new Error(`HTTP_${response.status}`);
+  if (!response.ok) throw httpError(response);
   return await response.json();
 }
 function parseTargetId(url) {
@@ -6347,7 +6716,7 @@ async function addWorkItemRelation(context, cred, type, id1, id2) {
       { op: "add", path: "/relations/-", value: { rel: relType.referenceName, url: targetUrl } }
     ])
   });
-  if (!response.ok) throw new Error(`HTTP_${response.status}`);
+  if (!response.ok) throw httpError(response);
   return { status: "added", type: relType.name, referenceName: relType.referenceName, id1, id2 };
 }
 async function removeWorkItemRelation(context, cred, type, id1, id2) {
@@ -6367,7 +6736,7 @@ async function removeWorkItemRelation(context, cred, type, id1, id2) {
     headers: { ...authHeaders(cred), "Content-Type": "application/json-patch+json" },
     body: JSON.stringify([{ op: "remove", path: `/relations/${index}` }])
   });
-  if (!response.ok) throw new Error(`HTTP_${response.status}`);
+  if (!response.ok) throw httpError(response);
   return { status: "removed", type: relType.name, referenceName: relType.referenceName, id1, id2 };
 }
 async function listWorkItemRelations(context, cred, id) {
@@ -6455,11 +6824,12 @@ function handleRelationError(err, id1) {
     const target = id1 !== void 0 ? id1 : "unknown";
     process.stderr.write(`Error: work item #${target} not found.
 `);
-  } else if (msg === "AUTH_FAILED") {
+  } else if (isSentinel(msg, "AUTH_FAILED")) {
     process.stderr.write(
       `Error: authentication failed. Check your PAT has Work Items \u2192 Read & Write scope.
 `
     );
+    writeErrorDetail(msg, "AUTH_FAILED");
   } else {
     process.stderr.write(`Error: ${msg}
 `);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "azdo-cli",
-  "version": "0.19.0-develop.691",
+  "version": "0.19.0-develop.710",
   "description": "Azure DevOps CLI tool",
   "type": "module",
   "bin": {