azdo-cli 0.19.0-feature-037-api-error-surfacing.693 → 0.19.0-feature-037-api-error-surfacing.695

package/README.md

@@ -89,6 +89,8 @@ azdo pr comment-reply 148 "Done."  --pr-number 64                        # flat
 # 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
+# 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.
 
 # Link/unlink a work item, add/remove reviewers
 azdo pr work-items link 1234 --pr-number 64

package/dist/index.js

@@ -78,6 +78,22 @@ function redactUrl(url) {
     return url;
   }
 }
+var SECRET_IN_TEXT = [
+  [/\b(Bearer|Basic)\s+[A-Za-z0-9._~+/=-]{8,}/gi, `$1 ${REDACTED}`],
+  [
+    /(\b(?:access[_-]?token|refresh[_-]?token|token|pat|password|secret|api[_-]?key)\b["']?\s*[:=]\s*["']?)[^"'\s,;&}]+/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 +139,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";
@@ -329,110 +470,111 @@ async function fetchRaw(url, init) {
 var MAX_DETAIL_CHARS = 500;
 var MAX_RAW_BODY_CHARS = 200;
 var failureDetails = /* @__PURE__ */ new WeakMap();
-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;
+function renderErrorFields(body, requireMessage = false) {
   let parsed;
   try {
-    parsed = JSON.parse(redacted);
+    parsed = JSON.parse(body);
   } catch {
-    return truncateDetail(redacted.slice(0, MAX_RAW_BODY_CHARS));
-  }
-  if (typeof parsed !== "object" || parsed === null) {
-    return truncateDetail(redacted.slice(0, MAX_RAW_BODY_CHARS));
+    return null;
   }
-  const record = parsed;
+  if (typeof parsed !== "object" || parsed === null) return null;
+  return renderErrorRecord(parsed, requireMessage);
+}
+function renderErrorRecord(record, requireMessage) {
   const parts = [];
-  if (typeof record.message === "string" && record.message.trim() !== "") {
-    parts.push(record.message.trim());
+  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}]`);
   }
-  if (parts.length === 0) {
-    return truncateDetail(redacted.slice(0, MAX_RAW_BODY_CHARS));
+  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;
   }
-  return truncateDetail(parts.join(" "));
+  const redacted = redactBody(trimmed) ?? trimmed;
+  return truncateDetail(renderErrorFields(redacted) ?? redacted.slice(0, MAX_RAW_BODY_CHARS));
 }
 function truncateDetail(detail) {
-  const collapsed = detail.replace(/\s+/g, " ").trim();
+  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 withDetail(sentinel, detail) {
-  return detail === null ? sentinel : `${sentinel}: ${detail}`;
-}
 function httpError(response) {
   return new Error(withDetail(`HTTP_${response.status}`, failureDetails.get(response) ?? null));
 }
-async function fetchWithErrors(url, init) {
+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 = "";
+  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 });
   }
-  let tracedBody = null;
-  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 {
-    }
-    tracedBody = 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: 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) {
-    let body = tracedBody;
-    if (body === null) {
-      try {
-        body = await response.clone().text();
-      } catch {
-        body = null;
-      }
-    }
+    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 (failureDetail !== null) failureDetails.set(response, failureDetail);
   }
   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 = tracedBody ?? await response.text();
-      detail = ` | url=${url} | body=${body}`;
-    } catch {
-    }
-    throw new Error(`NOT_FOUND${detail}`);
+    const body = failureBodies.get(response);
+    throw new Error(body === void 0 ? "NOT_FOUND" : `NOT_FOUND | url=${url} | body=${body}`);
   }
   if (contentType.toLowerCase().startsWith("text/html")) {
     throw new Error("AUTH_FAILED");
@@ -440,14 +582,18 @@ async function fetchWithErrors(url, init) {
   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)));
@@ -1609,128 +1755,6 @@ function toMarkdown(content) {
   return decodeEntitiesInMarkdownCodeSpans(decodeAdoEntitiesInMarkdown(content));
 }
 
-// src/services/command-helpers.ts
-function isSentinel(message, sentinel) {
-  return message === sentinel || message.startsWith(`${sentinel}: `);
-}
-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/commands/get-item.ts
 function parseRequestedFields(raw) {
   if (raw === void 0) return void 0;
@@ -3655,8 +3679,11 @@ function composeDescription(description, template) {
 }
 function formatDescriptionOverflow(composed) {
   const overflow = composed.totalChars - MAX_PR_DESCRIPTION_CHARS;
-  const breakdown = composed.templateChars > 0 && composed.providedChars > 0 ? ` (${composed.providedChars} provided + ${composed.separatorChars} separator + ${composed.templateChars} from the repository pull request template ${composed.templatePath})` : composed.templateChars > 0 ? ` (all of it from the repository pull request template ${composed.templatePath})` : "";
-  return `description is ${composed.totalChars} characters${breakdown}, exceeding the Azure DevOps limit of ${MAX_PR_DESCRIPTION_CHARS} characters. Shorten the description by at least ${overflow} characters.`;
+  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})`;
@@ -3901,7 +3928,7 @@ async function resolveReviewerIdentity(org, cred, input) {
     });
   } catch (err) {
     if (err instanceof Error && isSentinel(err.message, "AUTH_FAILED")) {
-      throw new Error("IDENTITY_SCOPE_MISSING", { cause: err });
+      throw new Error(withDetail("IDENTITY_SCOPE_MISSING", sentinelDetail(err.message, "AUTH_FAILED")), { cause: err });
     }
     throw err;
   }
@@ -4144,11 +4171,12 @@ function handlePrCommandError(err, context, mode = "read") {
     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 (isSentinel(error.message, "PERMISSION_DENIED")) {
@@ -4345,6 +4373,23 @@ 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 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(
@@ -4393,20 +4438,7 @@ ${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.");
-        return;
-      }
-      if (err instanceof Error && err.message.startsWith("DESCRIPTION_TOO_LONG: ")) {
-        writeError(err.message.slice("DESCRIPTION_TOO_LONG: ".length));
-        return;
-      }
-      handlePrCommandError(err, context, "write");
+      handlePrOpenError(err, context);
     }
   });
   return command;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "azdo-cli",
-  "version": "0.19.0-feature-037-api-error-surfacing.693",
+  "version": "0.19.0-feature-037-api-error-surfacing.695",
   "description": "Azure DevOps CLI tool",
   "type": "module",
   "bin": {