azdo-cli 0.15.0-develop.593 → 0.15.0-develop.604

package/README.md

@@ -54,20 +54,34 @@ azdo upsert --type "User Story" --content $'---\nTitle: Improve markdown import
 azdo comments list 12345
 azdo comments add 12345 "Investigating the root cause now."
 
+# Find a pull request — one API call, any branch
+azdo pr list                            # active PRs in the repository
+azdo pr list --branch feature/x --json  # id, title, source/target, author, url, description
+azdo pr list --status all --top 50
+
 # PR comment threads — list, filter, target by number, resolve or reopen
 azdo pr comments                        # active-branch PR; code-anchored threads show file:line
 azdo pr comments --pr-number 64         # any PR by number (skips branch lookup)
 azdo pr comments --pr-number 64 --hide-resolved      # or --exclude-resolved (alias)
 azdo pr comments --code-related-only    # only file/line-anchored threads
+azdo pr comments --exclude-system --max-chars 500    # human comments only, truncated
+azdo pr comments --thread 148           # a single thread, by id (selector: exit 1 if absent)
+azdo pr comments --contains '"kind":"review-plan"'   # threads holding a literal substring
 azdo pr status                          # PR checks (status + branch policies + pipeline builds) + code-comment counts
 azdo pr comment-resolve 17 --pr-number 64   # idempotent: exit 0 even when already resolved
 azdo pr comment-reopen 17  --pr-number 64
 
-# Reply to a PR comment thread
+# Write to a PR — new thread, in-place edit, reply
+azdo pr comments add --file plan.md --pr-number 64 --dry-run   # preview, writes nothing
+azdo pr comments add --file plan.md --pr-number 64             # NEW thread on the overview
+azdo pr comments edit 148 --file plan.md --pr-number 64        # rewrite it in place
 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
 
+# Any pr subcommand can target another repository
+azdo pr comments --repo other-repo --pr-number 12
+
 # Pipelines — list, inspect runs, wait (exit code = result), start
 azdo pipeline list --filter ci
 azdo pipeline get-runs 12 --branch develop --limit 1

package/dist/index.js

@@ -769,13 +769,29 @@ async function resolveAuthCredential(org) {
   }
   return null;
 }
+var lastResolvedCredential = null;
 async function requireAuthCredential(org) {
   const cred = await resolveAuthCredential(org);
   if (cred !== null) {
+    lastResolvedCredential = { credential: cred, org };
     return cred;
   }
   throw new CredentialMissingError(org);
 }
+function describeResolvedCredential() {
+  if (lastResolvedCredential === null) {
+    return null;
+  }
+  const { credential, org } = lastResolvedCredential;
+  if (credential.source === "env") {
+    return "Token used: PAT from the AZDO_PAT environment variable (it takes precedence over the stored credential). Fix: give that token the scope above, or unset AZDO_PAT to fall back to the stored credential.";
+  }
+  if (credential.source === "credential-store") {
+    const kind = credential.kind === "oauth" ? "OAuth access token" : "PAT";
+    return `Token used: ${kind} stored for org "${org}" in the OS credential store. Fix: run \`azdo auth login --org ${org}\` with an account or token carrying the scope above.`;
+  }
+  return "Token used: PAT entered at the prompt. Fix: re-enter a token carrying the scope above.";
+}
 async function validatePatAgainstAzdo(pat, org) {
   const url = `https://dev.azure.com/${encodeURIComponent(org)}/_apis/projects?$top=1&api-version=7.1`;
   const auth = Buffer.from(`:${pat}`).toString("base64");
@@ -1781,6 +1797,27 @@ async function runConnectivityTest(org, cred) {
   }
   return { status: "failed", error };
 }
+async function resolveCredentialIdentity(org, cred) {
+  const url = `https://dev.azure.com/${encodeURIComponent(org)}/_apis/connectionData?api-version=7.1`;
+  try {
+    const result = await fetchRaw(url, { headers: authHeaders(cred) });
+    if (result.status < 200 || result.status >= 300) {
+      return null;
+    }
+    const parsed = JSON.parse(result.body);
+    const user = parsed.authenticatedUser;
+    if (user === void 0) {
+      return null;
+    }
+    return {
+      displayName: user.providerDisplayName ?? null,
+      uniqueName: user.properties?.Account?.$value ?? null,
+      id: user.id ?? null
+    };
+  } catch {
+    return null;
+  }
+}
 async function diagnoseAuth(org, project, resolveCredential) {
   const cred = await resolveCredential(org);
   if (cred === null) {
@@ -1790,19 +1827,22 @@ async function diagnoseAuth(org, project, resolveCredential) {
       org,
       project,
       connectivityStatus: "no-credentials",
-      connectivityError: null
+      connectivityError: null,
+      identity: null
     };
   }
   const connectivity = await runConnectivityTest(org, cred);
   const envVarName = process.env.AZDO_PAT ? "AZDO_PAT" : "dotenv";
   const sourceLabel = cred.source === "env" ? `env:${envVarName}` : "credential-store";
+  const identity = connectivity.status === "ok" ? await resolveCredentialIdentity(org, cred) : null;
   return {
     authType: cred.kind ?? "pat",
     credentialSource: sourceLabel,
     org,
     project,
     connectivityStatus: connectivity.status,
-    connectivityError: connectivity.error
+    connectivityError: connectivity.error,
+    identity
   };
 }
 function formatDiagnosticReport(report, json) {
@@ -1824,6 +1864,13 @@ function formatDiagnosticReport(report, json) {
     `Project:      ${report.project ?? "(not set)"}`,
     `Connectivity: ${connectivityLine}`
   ];
+  const identity = report.identity;
+  if (identity) {
+    lines.push(`Identity:     ${identity.displayName ?? "(unknown name)"} <${identity.uniqueName ?? "(unknown account)"}>`);
+    if (identity.id) {
+      lines.push(`Identity id:  ${identity.id}`);
+    }
+  }
   if (report.connectivityStatus === "failed" && report.connectivityError !== null) {
     lines.push(`Error:        ${report.connectivityError}`);
   }
@@ -2366,6 +2413,21 @@ async function promptForSetting(cfg, setting, ask) {
 function createConfigCommand() {
   const config = new Command4("config");
   config.description("Manage CLI settings");
+  config.addHelpText(
+    "after",
+    [
+      "",
+      "Credentials are NOT stored in the configuration file. They are resolved in this order:",
+      "  1. the AZDO_PAT environment variable (wins over everything below)",
+      "  2. the OS credential store, per organization (see `azdo auth login`)",
+      "  3. a .env file with AZDO_PAT, searched upwards from the working directory",
+      "",
+      "Only AZDO_PAT is read \u2014 AZURE_DEVOPS_PAT, AZURE_DEVOPS_EXT_PAT and AZDO_TOKEN are ignored.",
+      "A pull request command needs a credential with the Code (Read) scope, or Code (Read & Write)",
+      "to post, edit or resolve comments; Work Items scopes alone are not enough.",
+      "Run `azdo auth diagnose` to see which credential is in use."
+    ].join("\n")
+  );
   const set = new Command4("set");
   set.description("Set a configuration value").argument("<key>", "setting key (org, project, fields, markdown)").argument("<value>", "setting value").option("--org <org>", "set value in an org-scoped configuration").option("--json", "output in JSON format").action((key, value, options) => {
     try {
@@ -3158,6 +3220,7 @@ function createListFieldsCommand() {
 }
 
 // src/commands/pr.ts
+import { existsSync as existsSync5, readFileSync as readFileSync5 } from "fs";
 import { Command as Command12 } from "commander";
 
 // src/services/pr-client.ts
@@ -3166,13 +3229,18 @@ function buildPullRequestsUrl(context, repo, sourceBranch, opts) {
     `https://dev.azure.com/${encodeURIComponent(context.org)}/${encodeURIComponent(context.project)}/_apis/git/repositories/${encodeURIComponent(repo)}/pullrequests`
   );
   url.searchParams.set("api-version", "7.1");
-  url.searchParams.set("searchCriteria.sourceRefName", `refs/heads/${sourceBranch}`);
+  if (sourceBranch !== null) {
+    url.searchParams.set("searchCriteria.sourceRefName", `refs/heads/${sourceBranch}`);
+  }
   if (opts?.status) {
     url.searchParams.set("searchCriteria.status", opts.status);
   }
   if (opts?.targetBranch) {
     url.searchParams.set("searchCriteria.targetRefName", `refs/heads/${opts.targetBranch}`);
   }
+  if (opts?.top !== void 0) {
+    url.searchParams.set("$top", String(opts.top));
+  }
   return url;
 }
 function buildPullRequestStatusesUrl(context, repo, prId) {
@@ -3207,7 +3275,10 @@ function buildPullRequestBuildsUrl(context, prId) {
   url.searchParams.set("api-version", "7.1");
   return url;
 }
-function mapPullRequest(repo, pullRequest) {
+function buildPullRequestWebUrl(context, repo, prId) {
+  return `https://dev.azure.com/${encodeURIComponent(context.org)}/${encodeURIComponent(context.project)}/_git/${encodeURIComponent(repo)}/pullrequest/${prId}`;
+}
+function mapPullRequest(context, repo, pullRequest) {
   return {
     id: pullRequest.pullRequestId,
     title: pullRequest.title,
@@ -3216,7 +3287,10 @@ function mapPullRequest(repo, pullRequest) {
     targetRefName: pullRequest.targetRefName,
     status: pullRequest.status,
     createdBy: pullRequest.createdBy?.displayName ?? null,
-    url: pullRequest._links?.web?.href ?? null
+    url: pullRequest._links?.web?.href ?? buildPullRequestWebUrl(context, repo, pullRequest.pullRequestId),
+    description: pullRequest.description?.trim() || null,
+    createdByUniqueName: pullRequest.createdBy?.uniqueName ?? null,
+    createdById: pullRequest.createdBy?.id ?? null
   };
 }
 function mapPullRequestCheckName(status2) {
@@ -3316,7 +3390,8 @@ function mapComment(comment) {
     id: comment.id,
     author: comment.author?.displayName ?? null,
     content,
-    publishedAt: comment.publishedDate ?? null
+    publishedAt: comment.publishedDate ?? null,
+    commentType: comment.commentType ?? null
   };
 }
 function mapThread(thread) {
@@ -3376,7 +3451,7 @@ async function getPullRequestById(context, repo, cred, prId) {
   url.searchParams.set("api-version", "7.1");
   const response = await fetchWithErrors(url.toString(), { headers: authHeaders(cred) });
   const data = await readJsonResponse(response);
-  return mapPullRequest(repo, data);
+  return mapPullRequest(context, repo, data);
 }
 async function listPullRequests(context, repo, cred, sourceBranch, opts) {
   const response = await fetchWithErrors(
@@ -3384,7 +3459,16 @@ async function listPullRequests(context, repo, cred, sourceBranch, opts) {
     { headers: authHeaders(cred) }
   );
   const data = await readJsonResponse(response);
-  return data.value.map((pullRequest) => mapPullRequest(repo, pullRequest));
+  return data.value.map((pullRequest) => mapPullRequest(context, repo, pullRequest));
+}
+async function listRepositoryPullRequests(context, repo, cred, opts) {
+  const url = buildPullRequestsUrl(context, repo, opts?.sourceBranch ?? null, {
+    status: opts?.status,
+    top: opts?.top
+  });
+  const response = await fetchWithErrors(url.toString(), { headers: authHeaders(cred) });
+  const data = await readJsonResponse(response);
+  return data.value.map((pullRequest) => mapPullRequest(context, repo, pullRequest));
 }
 async function getPullRequestChecks(context, repo, cred, prId) {
   const response = await fetchWithErrors(
@@ -3466,7 +3550,7 @@ async function openPullRequest(context, repo, cred, sourceBranch, title, descrip
     branch: sourceBranch,
     targetBranch: "develop",
     created: true,
-    pullRequest: mapPullRequest(repo, data)
+    pullRequest: mapPullRequest(context, repo, data)
   };
 }
 async function getPullRequestThreads(context, repo, cred, prId) {
@@ -3478,6 +3562,37 @@ async function getPullRequestThreads(context, repo, cred, prId) {
   const data = await readJsonResponse(response);
   return data.value.map(mapThread).filter((thread) => thread !== null);
 }
+async function getPullRequestThread(context, repo, cred, prId, threadId) {
+  const url = new URL(
+    `https://dev.azure.com/${encodeURIComponent(context.org)}/${encodeURIComponent(context.project)}/_apis/git/repositories/${encodeURIComponent(repo)}/pullRequests/${prId}/threads/${threadId}`
+  );
+  url.searchParams.set("api-version", "7.1");
+  const response = await fetchWithErrors(url.toString(), { headers: authHeaders(cred) });
+  const data = await readJsonResponse(response);
+  return toActiveCommentThread(data);
+}
+async function createPullRequestThread(context, repo, cred, prId, content, status2) {
+  const url = new URL(
+    `https://dev.azure.com/${encodeURIComponent(context.org)}/${encodeURIComponent(context.project)}/_apis/git/repositories/${encodeURIComponent(repo)}/pullRequests/${prId}/threads`
+  );
+  url.searchParams.set("api-version", "7.1");
+  const payload = {
+    comments: [{ parentCommentId: 0, content, commentType: 1 }]
+  };
+  if (status2 !== void 0) {
+    payload.status = status2;
+  }
+  const response = await fetchWithErrors(url.toString(), {
+    method: "POST",
+    headers: {
+      ...authHeaders(cred),
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify(payload)
+  });
+  const data = await readJsonResponse(response);
+  return toActiveCommentThread(data);
+}
 function buildThreadCommentUrl(context, repo, prId, threadId) {
   const url = new URL(
     `https://dev.azure.com/${encodeURIComponent(context.org)}/${encodeURIComponent(context.project)}/_apis/git/repositories/${encodeURIComponent(repo)}/pullRequests/${prId}/threads/${threadId}/comments`
@@ -3485,6 +3600,27 @@ function buildThreadCommentUrl(context, repo, prId, threadId) {
   url.searchParams.set("api-version", "7.1");
   return url;
 }
+async function updateThreadComment(context, repo, cred, prId, threadId, commentId, content) {
+  const url = new URL(
+    `https://dev.azure.com/${encodeURIComponent(context.org)}/${encodeURIComponent(context.project)}/_apis/git/repositories/${encodeURIComponent(repo)}/pullRequests/${prId}/threads/${threadId}/comments/${commentId}`
+  );
+  url.searchParams.set("api-version", "7.1");
+  const response = await fetchWithErrors(url.toString(), {
+    method: "PATCH",
+    headers: {
+      ...authHeaders(cred),
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify({ content })
+  });
+  const data = await readJsonResponse(response);
+  return {
+    id: data.id,
+    author: data.author?.displayName ?? null,
+    content: data.content ?? content,
+    publishedAt: data.publishedDate ?? null
+  };
+}
 async function postThreadComment(context, repo, cred, prId, threadId, content) {
   const response = await fetchWithErrors(buildThreadCommentUrl(context, repo, prId, threadId).toString(), {
     method: "POST",
@@ -3512,9 +3648,16 @@ function parsePositivePrNumber(raw) {
   return Number.isFinite(n) && n > 0 ? n : null;
 }
 var PR_NUMBER_HELP = "target the pull request with this numeric id, instead of the current branch's PR. When omitted, the CLI auto-detects the pull request whose source branch equals refs/heads/<current branch> in the Azure DevOps repository identified by the origin remote; if zero or more than one open PR matches, the command fails with a message naming the searched branch.";
+var PR_REPO_HELP = 'Azure DevOps repository name; defaults to the repository of the git "origin" remote';
 function configureUnwrappedHelp(command) {
   return command.configureHelp({ helpWidth: 1e3 });
 }
+function withCommonPrOptions(command) {
+  return command.option("--org <org>", "Azure DevOps organization").option("--project <project>", "Azure DevOps project").option("--repo <name>", PR_REPO_HELP);
+}
+function mergedPrOptions(command) {
+  return command.optsWithGlobals();
+}
 function autoDetectZeroMatch(branch) {
   return `No open pull request matches branch ${branch}. Pass --pr-number to target a specific PR, or push the branch and open a pull request.`;
 }
@@ -3527,23 +3670,74 @@ function writeContractError(line) {
 `);
   process.exitCode = 1;
 }
+var EMPTY_BODY_ERROR = "Comment text must not be empty. Pass the text inline or use --file <path>.";
+function resolveCommentBody(inline, file, emptyMessage = EMPTY_BODY_ERROR) {
+  if (inline !== void 0 && file !== void 0) {
+    writeError("Cannot specify both inline text and --file.");
+    return null;
+  }
+  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}`);
+      return null;
+    }
+  } else if (inline !== void 0) {
+    body = inline;
+  } else {
+    writeError(emptyMessage);
+    return null;
+  }
+  const trimmed = body.trim();
+  if (trimmed === "") {
+    writeError(emptyMessage);
+    return null;
+  }
+  return trimmed;
+}
+function parseNonNegativeInt(raw) {
+  if (!/^\d+$/.test(raw)) {
+    return null;
+  }
+  const n = Number.parseInt(raw, 10);
+  return Number.isFinite(n) ? n : null;
+}
+function truncateContent(text, limit) {
+  if (limit <= 0 || text.length <= limit) {
+    return { content: text, truncated: false, originalLength: text.length };
+  }
+  return { content: `${text.slice(0, limit)} [\u2026]`, truncated: true, originalLength: text.length };
+}
 function formatBranchName(refName) {
   return refName.startsWith("refs/heads/") ? refName.slice("refs/heads/".length) : refName;
 }
-function writeError(message) {
+var EXIT_NOT_FOUND = 3;
+var EXIT_NOT_PERMITTED = 4;
+function writeError(message, exitCode = 1) {
   process.stderr.write(`Error: ${message}
 `);
-  process.exitCode = 1;
+  process.exitCode = exitCode;
 }
 function handlePrCommandError(err, context, mode = "read") {
   const error = err instanceof Error ? err : new Error(String(err));
   if (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.`);
+    writeError(`Authentication failed. Check that your PAT is valid and has the "${scopeLabel}" scope.`, EXIT_NOT_PERMITTED);
+    const credentialHint = describeResolvedCredential();
+    if (credentialHint !== null) {
+      process.stderr.write(`  ${credentialHint}
+`);
+    }
     return;
   }
   if (error.message === "PERMISSION_DENIED") {
-    writeError(`Access denied. Your PAT may lack ${mode} permissions for project "${context?.project}".`);
+    writeError(`Access denied. Your PAT may lack ${mode} permissions for project "${context?.project}".`, EXIT_NOT_PERMITTED);
     return;
   }
   if (error.message === "NETWORK_ERROR") {
@@ -3551,7 +3745,7 @@ function handlePrCommandError(err, context, mode = "read") {
     return;
   }
   if (error.message.startsWith("NOT_FOUND")) {
-    writeError(`Azure DevOps repository not found in ${context?.org}/${context?.project}.`);
+    writeError(`Azure DevOps repository not found in ${context?.org}/${context?.project}.`, EXIT_NOT_FOUND);
     return;
   }
   if (error.message.startsWith("HTTP_")) {
@@ -3649,6 +3843,22 @@ async function buildPullRequestStatusEntry(context, repo, cred, pullRequest, pro
 function threadStatusLabel(status2) {
   return isThreadResolved(status2) ? "resolved" : status2;
 }
+function shapeThreadForOutput(thread, opts) {
+  const kept = thread.comments.filter(
+    (comment) => !opts.excludeSystem || comment.commentType !== "system"
+  );
+  if (opts.excludeSystem && kept.length === 0) {
+    return null;
+  }
+  if (opts.contains !== void 0 && !kept.some((comment) => comment.content.includes(opts.contains))) {
+    return null;
+  }
+  const comments = kept.map((comment) => ({
+    ...comment,
+    ...truncateContent(comment.content, opts.maxChars)
+  }));
+  return { ...thread, comments };
+}
 function formatThreads(prId, title, threads) {
   const lines = [`Comment threads for pull request #${prId}: ${title}`];
   for (const thread of threads) {
@@ -3664,7 +3874,7 @@ function formatThreads(prId, title, threads) {
 async function resolvePrCommandContext(options, resolveOpts = {}) {
   const requireBranch = resolveOpts.requireBranch ?? true;
   const context = resolveContext(options);
-  const repo = detectRepoName();
+  const repo = options.repo?.trim() || detectRepoName();
   const branch = requireBranch ? getCurrentBranch() : null;
   const credential = await requireAuthCredential(context.org);
   return {
@@ -3676,7 +3886,7 @@ async function resolvePrCommandContext(options, resolveOpts = {}) {
 }
 function createPrStatusCommand() {
   const command = new Command12("status");
-  command.description("Check pull requests for the current branch").option("--org <org>", "Azure DevOps organization").option("--project <project>", "Azure DevOps project").option("--json", "output JSON").action(async (options) => {
+  withCommonPrOptions(command).description("Check pull requests for the current branch").option("--json", "output JSON").action(async (options) => {
     validateOrgProjectPair(options);
     let context;
     try {
@@ -3716,7 +3926,7 @@ function createPrStatusCommand() {
 }
 function createPrOpenCommand() {
   const command = new Command12("open");
-  command.description("Open a pull request from the current branch to develop").option("--title <title>", "pull request title").option("--description <description>", "pull request description").option("--org <org>", "Azure DevOps organization").option("--project <project>", "Azure DevOps project").option("--json", "output JSON").action(async (options) => {
+  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").option("--json", "output JSON").action(async (options) => {
     validateOrgProjectPair(options);
     const title = options.title?.trim();
     if (!title) {
@@ -3774,7 +3984,7 @@ ${result.pullRequest.url ?? "\u2014"}
 }
 function createPrCommentsCommand() {
   const command = new Command12("comments");
-  configureUnwrappedHelp(command).description("List pull request comment threads for the current branch").option("--org <org>", "Azure DevOps organization").option("--project <project>", "Azure DevOps project").option("--pr-number <N>", PR_NUMBER_HELP).option("--hide-resolved", "hide threads whose status is resolved / won't fix / closed / by design").option("--exclude-resolved", "alias of --hide-resolved: exclude resolved / won't fix / closed / by design threads").option("--code-related-only", "show only threads anchored to a file/line; omit general discussion threads").option("--json", "output JSON").action(async (options) => {
+  withCommonPrOptions(configureUnwrappedHelp(command)).description("List pull request comment threads for the current branch").option("--pr-number <N>", PR_NUMBER_HELP).option("--hide-resolved", "hide threads whose status is resolved / won't fix / closed / by design").option("--exclude-resolved", "alias of --hide-resolved: exclude resolved / won't fix / closed / by design threads").option("--code-related-only", "show only threads anchored to a file/line; omit general discussion threads").option("--exclude-system", "omit Azure DevOps system comments (branch updates, reviewer votes, build events)").option("--max-chars <N>", "truncate each comment body to N characters (0 = no limit, the default)").option("--thread <id>", "show only the thread with this numeric id; fails when the pull request has no such thread").option("--contains <text>", "show only threads holding a comment that contains this literal, case-sensitive substring (matched before --max-chars truncates)").option("--json", "output JSON").action(async (options) => {
     validateOrgProjectPair(options);
     let context;
     let explicitPrId = null;
@@ -3785,6 +3995,23 @@ function createPrCommentsCommand() {
         return;
       }
     }
+    let maxChars = 0;
+    if (options.maxChars !== void 0) {
+      const parsed = parseNonNegativeInt(options.maxChars);
+      if (parsed === null) {
+        writeError(`Invalid --max-chars "${options.maxChars}"; expected a non-negative integer.`);
+        return;
+      }
+      maxChars = parsed;
+    }
+    let threadFilter = null;
+    if (options.thread !== void 0) {
+      threadFilter = parsePositivePrNumber(options.thread);
+      if (threadFilter === null) {
+        writeError(`Invalid --thread "${options.thread}"; expected a positive integer.`);
+        return;
+      }
+    }
     try {
       const resolved = await resolvePrCommandContext(options, { requireBranch: explicitPrId === null });
       context = resolved.context;
@@ -3795,7 +4022,7 @@ function createPrCommentsCommand() {
           pullRequest = await getPullRequestById(resolved.context, resolved.repo, resolved.pat, explicitPrId);
         } catch (err) {
           if (err instanceof Error && err.message.startsWith("NOT_FOUND")) {
-            writeError(`Pull request #${explicitPrId} not found in ${resolved.context.org}/${resolved.context.project}/${resolved.repo}.`);
+            writeError(`Pull request #${explicitPrId} not found in ${resolved.context.org}/${resolved.context.project}/${resolved.repo}.`, EXIT_NOT_FOUND);
             return;
           }
           throw err;
@@ -3818,10 +4045,16 @@ function createPrCommentsCommand() {
       }
       const hideResolved = options.hideResolved === true || options.excludeResolved === true;
       const codeRelatedOnly = options.codeRelatedOnly === true;
-      const allThreads = await getPullRequestThreads(resolved.context, resolved.repo, resolved.pat, pullRequest.id);
+      const excludeSystem = options.excludeSystem === true;
+      const fetchedThreads = await getPullRequestThreads(resolved.context, resolved.repo, resolved.pat, pullRequest.id);
+      if (threadFilter !== null && !fetchedThreads.some((thread) => thread.id === threadFilter)) {
+        writeError(`Thread #${threadFilter} not found on pull request #${pullRequest.id}.`, EXIT_NOT_FOUND);
+        return;
+      }
+      const allThreads = threadFilter === null ? fetchedThreads : fetchedThreads.filter((thread) => thread.id === threadFilter);
       const threads = allThreads.filter(
         (thread) => (!hideResolved || !isThreadResolved(thread.status)) && (!codeRelatedOnly || thread.threadContext !== null)
-      );
+      ).map((thread) => shapeThreadForOutput(thread, { excludeSystem, maxChars, contains: options.contains })).filter((thread) => thread !== null);
       const result = { branch: branchLabel, pullRequest, threads };
       if (options.json) {
         process.stdout.write(`${JSON.stringify(result, null, 2)}
@@ -3829,14 +4062,20 @@ function createPrCommentsCommand() {
         return;
       }
       if (threads.length === 0) {
-        if (allThreads.length > 0 && (hideResolved || codeRelatedOnly)) {
+        if (allThreads.length > 0 && (hideResolved || codeRelatedOnly || excludeSystem || options.contains !== void 0)) {
           const filters = [];
+          if (options.contains !== void 0) {
+            filters.push("matching");
+          }
           if (codeRelatedOnly) {
             filters.push("code-related");
           }
           if (hideResolved) {
             filters.push("unresolved");
           }
+          if (excludeSystem) {
+            filters.push("non-system");
+          }
           process.stdout.write(
             `Pull request #${pullRequest.id} has no ${filters.join(" ")} comment threads (filtered from ${allThreads.length} thread${allThreads.length === 1 ? "" : "s"}).
 `
@@ -3854,15 +4093,12 @@ function createPrCommentsCommand() {
     }
   });
   command.addCommand(createPrCommentsReplyCommand());
+  command.addCommand(createPrCommentsAddCommand());
+  command.addCommand(createPrCommentsEditCommand());
   return command;
 }
-async function resolveThreadTarget(threadIdRaw, options) {
+async function resolvePullRequestTarget(options) {
   validateOrgProjectPair(options);
-  const threadId = parsePositivePrNumber(threadIdRaw);
-  if (threadId === null) {
-    writeError(`Invalid thread id "${threadIdRaw}"; expected a positive integer.`);
-    return null;
-  }
   let explicitPrId = null;
   if (options.prNumber !== void 0) {
     explicitPrId = parsePositivePrNumber(options.prNumber);
@@ -3878,7 +4114,7 @@ async function resolveThreadTarget(threadIdRaw, options) {
       pullRequest = await getPullRequestById(resolved.context, resolved.repo, resolved.pat, explicitPrId);
     } catch (err) {
       if (err instanceof Error && err.message.startsWith("NOT_FOUND")) {
-        writeError(`Pull request #${explicitPrId} not found in ${resolved.context.org}/${resolved.context.project}/${resolved.repo}.`);
+        writeError(`Pull request #${explicitPrId} not found in ${resolved.context.org}/${resolved.context.project}/${resolved.repo}.`, EXIT_NOT_FOUND);
         return null;
       }
       throw err;
@@ -3897,7 +4133,20 @@ async function resolveThreadTarget(threadIdRaw, options) {
     }
     pullRequest = pullRequests[0];
   }
-  return { context: resolved.context, repo: resolved.repo, pat: resolved.pat, pullRequest, threadId };
+  return { context: resolved.context, repo: resolved.repo, pat: resolved.pat, pullRequest };
+}
+async function resolveThreadTarget(threadIdRaw, options) {
+  const threadId = parsePositivePrNumber(threadIdRaw);
+  if (threadId === null) {
+    validateOrgProjectPair(options);
+    writeError(`Invalid thread id "${threadIdRaw}"; expected a positive integer.`);
+    return null;
+  }
+  const target = await resolvePullRequestTarget(options);
+  if (target === null) {
+    return null;
+  }
+  return { ...target, threadId };
 }
 async function runThreadStateChange(threadIdRaw, options, direction) {
   let context;
@@ -3910,7 +4159,7 @@ async function runThreadStateChange(threadIdRaw, options, direction) {
     const threads = await getPullRequestThreads(target.context, target.repo, target.pat, target.pullRequest.id);
     const thread = threads.find((t) => t.id === target.threadId);
     if (!thread) {
-      writeError(`Thread #${target.threadId} not found on pull request #${target.pullRequest.id}.`);
+      writeError(`Thread #${target.threadId} not found on pull request #${target.pullRequest.id}.`, EXIT_NOT_FOUND);
       return;
     }
     const alreadyInTargetState = direction === "resolve" ? isThreadResolved(thread.status) : !isThreadResolved(thread.status);
@@ -3960,14 +4209,14 @@ async function runThreadStateChange(threadIdRaw, options, direction) {
 }
 function createPrCommentResolveCommand() {
   const command = new Command12("comment-resolve");
-  configureUnwrappedHelp(command).description("Mark a pull request comment thread as resolved").argument("<threadId>", "numeric id of the thread to resolve").option("--org <org>", "Azure DevOps organization").option("--project <project>", "Azure DevOps project").option("--pr-number <N>", PR_NUMBER_HELP).option("--json", "output JSON").action(async (threadIdRaw, options) => {
+  withCommonPrOptions(configureUnwrappedHelp(command)).description("Mark a pull request comment thread as resolved").argument("<threadId>", "numeric id of the thread to resolve").option("--pr-number <N>", PR_NUMBER_HELP).option("--json", "output JSON").action(async (threadIdRaw, options) => {
     await runThreadStateChange(threadIdRaw, options, "resolve");
   });
   return command;
 }
 function createPrCommentReopenCommand() {
   const command = new Command12("comment-reopen");
-  configureUnwrappedHelp(command).description("Reopen (set to active) a previously resolved pull request comment thread").argument("<threadId>", "numeric id of the thread to reopen").option("--org <org>", "Azure DevOps organization").option("--project <project>", "Azure DevOps project").option("--pr-number <N>", PR_NUMBER_HELP).option("--json", "output JSON").action(async (threadIdRaw, options) => {
+  withCommonPrOptions(configureUnwrappedHelp(command)).description("Reopen (set to active) a previously resolved pull request comment thread").argument("<threadId>", "numeric id of the thread to reopen").option("--pr-number <N>", PR_NUMBER_HELP).option("--json", "output JSON").action(async (threadIdRaw, options) => {
     await runThreadStateChange(threadIdRaw, options, "reopen");
   });
   return command;
@@ -3975,9 +4224,8 @@ function createPrCommentReopenCommand() {
 async function runCommentReply(threadIdRaw, text, options) {
   let context;
   try {
-    const trimmedText = text.trim();
-    if (!trimmedText) {
-      writeError("Reply text must not be empty.");
+    const trimmedText = resolveCommentBody(text, options.file, "Reply text must not be empty.");
+    if (trimmedText === null) {
       return;
     }
     const target = await resolveThreadTarget(threadIdRaw, options);
@@ -3988,7 +4236,7 @@ async function runCommentReply(threadIdRaw, text, options) {
     const threads = await getPullRequestThreads(target.context, target.repo, target.pat, target.pullRequest.id);
     const thread = threads.find((t) => t.id === target.threadId);
     if (!thread) {
-      writeError(`Thread #${target.threadId} not found on pull request #${target.pullRequest.id}.`);
+      writeError(`Thread #${target.threadId} not found on pull request #${target.pullRequest.id}.`, EXIT_NOT_FOUND);
       return;
     }
     const posted = await postThreadComment(
@@ -4016,29 +4264,333 @@ async function runCommentReply(threadIdRaw, text, options) {
     handlePrCommandError(err, context, "write");
   }
 }
-function createPrCommentsReplyCommand() {
-  const command = new Command12("reply");
-  configureUnwrappedHelp(command).description("Post a reply to a pull request comment thread").argument("<threadId>", "numeric id of the thread to reply to").argument("<text>", "text of the reply").option("--org <org>", "Azure DevOps organization").option("--project <project>", "Azure DevOps project").option("--pr-number <N>", PR_NUMBER_HELP).option("--json", "output JSON").action(async (threadIdRaw, text, options) => {
-    await runCommentReply(threadIdRaw, text, options);
+function buildCommentReplyCommand(name, description) {
+  const command = new Command12(name);
+  withCommonPrOptions(configureUnwrappedHelp(command)).description(description).argument("<threadId>", "numeric id of the thread to reply to").argument("[text]", "text of the reply; omit when using --file").option("--file <path>", "read the reply body from a UTF-8 file instead of the inline argument").option("--pr-number <N>", PR_NUMBER_HELP).option("--json", "output JSON").action(async (threadIdRaw, text, _options, command2) => {
+    await runCommentReply(threadIdRaw, text, mergedPrOptions(command2));
   });
   return command;
 }
+function createPrCommentsReplyCommand() {
+  return buildCommentReplyCommand("reply", "Post a reply to a pull request comment thread");
+}
 function createPrCommentReplyCommand() {
-  const command = new Command12("comment-reply");
-  configureUnwrappedHelp(command).description('Post a reply to a pull request comment thread (alias of "azdo pr comments reply")').argument("<threadId>", "numeric id of the thread to reply to").argument("<text>", "text of the reply").option("--org <org>", "Azure DevOps organization").option("--project <project>", "Azure DevOps project").option("--pr-number <N>", PR_NUMBER_HELP).option("--json", "output JSON").action(async (threadIdRaw, text, options) => {
-    await runCommentReply(threadIdRaw, text, options);
+  return buildCommentReplyCommand(
+    "comment-reply",
+    'Post a reply to a pull request comment thread (alias of "azdo pr comments reply")'
+  );
+}
+var CREATABLE_THREAD_STATUSES = [
+  "active",
+  "fixed",
+  "wontFix",
+  "closed",
+  "byDesign",
+  "pending"
+];
+async function runCommentAdd(text, options) {
+  let context;
+  try {
+    const body = resolveCommentBody(text, options.file);
+    if (body === null) {
+      return;
+    }
+    let status2;
+    if (options.status !== void 0) {
+      const match = CREATABLE_THREAD_STATUSES.find((candidate) => candidate === options.status);
+      if (match === void 0) {
+        writeError(
+          `Invalid --status "${options.status}"; expected one of ${CREATABLE_THREAD_STATUSES.join(", ")}.`
+        );
+        return;
+      }
+      status2 = match;
+    }
+    const target = await resolvePullRequestTarget(options);
+    if (target === null) {
+      return;
+    }
+    context = target.context;
+    if (options.dryRun === true) {
+      const dryResult = {
+        pullRequestId: target.pullRequest.id,
+        threadId: null,
+        commentId: null,
+        status: status2 ?? null,
+        content: body,
+        dryRun: true
+      };
+      if (options.json) {
+        process.stdout.write(`${JSON.stringify(dryResult, null, 2)}
+`);
+        return;
+      }
+      const statusSuffix = status2 === void 0 ? "" : ` with status ${status2}`;
+      process.stdout.write(
+        `Dry run: would post a new comment thread${statusSuffix} on pull request #${target.pullRequest.id} (${body.length} chars).
+${body}
+`
+      );
+      return;
+    }
+    const thread = await createPullRequestThread(
+      target.context,
+      target.repo,
+      target.pat,
+      target.pullRequest.id,
+      body,
+      status2
+    );
+    const created = thread.comments[0];
+    const result = {
+      pullRequestId: target.pullRequest.id,
+      threadId: thread.id,
+      commentId: created?.id ?? null,
+      status: thread.status,
+      content: created?.content ?? body,
+      dryRun: false
+    };
+    if (options.json) {
+      process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+      return;
+    }
+    process.stdout.write(
+      `Comment posted to pull request #${target.pullRequest.id} (thread #${thread.id}).
+`
+    );
+  } catch (err) {
+    handlePrCommandError(err, context, "write");
+  }
+}
+function buildCommentAddCommand(name, description) {
+  const command = new Command12(name);
+  withCommonPrOptions(configureUnwrappedHelp(command)).description(description).argument("[text]", "body of the new comment; omit when using --file").option("--file <path>", "read the comment body from a UTF-8 file instead of the inline argument").option(
+    "--status <status>",
+    `thread status (${CREATABLE_THREAD_STATUSES.join(" | ")}); omit for a plain, non-resolvable comment`
+  ).option("--dry-run", "resolve the target pull request and print what would be posted, without writing anything").option("--pr-number <N>", PR_NUMBER_HELP).option("--json", "output JSON").action(async (text, _options, command2) => {
+    await runCommentAdd(text, mergedPrOptions(command2));
+  });
+  return command;
+}
+function createPrCommentsAddCommand() {
+  return buildCommentAddCommand("add", "Post a new comment thread on the pull request overview");
+}
+function createPrCommentAddCommand() {
+  return buildCommentAddCommand(
+    "comment-add",
+    'Post a new comment thread on the pull request overview (alias of "azdo pr comments add")'
+  );
+}
+async function fetchThreadForEdit(target) {
+  try {
+    return await getPullRequestThread(
+      target.context,
+      target.repo,
+      target.pat,
+      target.pullRequest.id,
+      target.threadId
+    );
+  } catch (err) {
+    if (err instanceof Error && err.message.startsWith("NOT_FOUND")) {
+      writeError(`Thread #${target.threadId} not found on pull request #${target.pullRequest.id}.`, EXIT_NOT_FOUND);
+      return null;
+    }
+    throw err;
+  }
+}
+function selectEditableComment(thread, explicitCommentId, target) {
+  if (explicitCommentId !== null) {
+    const match = thread.comments.find((comment) => comment.id === explicitCommentId);
+    if (match === void 0) {
+      writeError(`Comment #${explicitCommentId} not found in thread #${target.threadId} on pull request #${target.pullRequest.id}.`, EXIT_NOT_FOUND);
+      return null;
+    }
+    return match;
+  }
+  const first = [...thread.comments].sort((a, b) => a.id - b.id)[0];
+  if (first === void 0) {
+    writeError(`Thread #${target.threadId} on pull request #${target.pullRequest.id} has no editable comment.`, EXIT_NOT_FOUND);
+    return null;
+  }
+  return first;
+}
+function reportEditResult(result, json) {
+  if (json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+    return;
+  }
+  if (result.dryRun) {
+    process.stdout.write(
+      `Dry run: would replace comment #${result.commentId} in thread #${result.threadId} on pull request #${result.pullRequestId} (${result.previousContent.length} chars -> ${result.content.length} chars).
+${result.content}
+`
+    );
+    return;
+  }
+  process.stdout.write(
+    `Comment #${result.commentId} updated in thread #${result.threadId} on pull request #${result.pullRequestId}.
+`
+  );
+}
+async function runCommentEdit(threadIdRaw, text, options) {
+  let context;
+  try {
+    const body = resolveCommentBody(text, options.file);
+    if (body === null) {
+      return;
+    }
+    let explicitCommentId = null;
+    if (options.commentId !== void 0) {
+      explicitCommentId = parsePositivePrNumber(options.commentId);
+      if (explicitCommentId === null) {
+        writeError(`Invalid --comment-id "${options.commentId}"; expected a positive integer.`);
+        return;
+      }
+    }
+    const target = await resolveThreadTarget(threadIdRaw, options);
+    if (target === null) {
+      return;
+    }
+    context = target.context;
+    const thread = await fetchThreadForEdit(target);
+    if (thread === null) {
+      return;
+    }
+    const existing = selectEditableComment(thread, explicitCommentId, target);
+    if (existing === null) {
+      return;
+    }
+    if (options.dryRun === true) {
+      reportEditResult(
+        {
+          pullRequestId: target.pullRequest.id,
+          threadId: target.threadId,
+          commentId: existing.id,
+          previousContent: existing.content,
+          content: body,
+          dryRun: true
+        },
+        options.json === true
+      );
+      return;
+    }
+    const updated = await updateThreadComment(
+      target.context,
+      target.repo,
+      target.pat,
+      target.pullRequest.id,
+      target.threadId,
+      existing.id,
+      body
+    );
+    reportEditResult(
+      {
+        pullRequestId: target.pullRequest.id,
+        threadId: target.threadId,
+        commentId: updated.id,
+        previousContent: existing.content,
+        content: updated.content,
+        dryRun: false
+      },
+      options.json === true
+    );
+  } catch (err) {
+    handlePrCommandError(err, context, "write");
+  }
+}
+function buildCommentEditCommand(name, description) {
+  const command = new Command12(name);
+  withCommonPrOptions(configureUnwrappedHelp(command)).description(description).argument("<threadId>", "numeric id of the thread holding the comment").argument("[text]", "new comment body; omit when using --file").option("--comment-id <N>", "numeric id of the comment to edit; defaults to the thread's first comment").option("--file <path>", "read the new body from a UTF-8 file instead of the inline argument").option("--dry-run", "print the replacement body plus the current/new lengths, without writing anything (--json also returns previousContent)").option("--pr-number <N>", PR_NUMBER_HELP).option("--json", "output JSON").action(async (threadIdRaw, text, _options, command2) => {
+    await runCommentEdit(threadIdRaw, text, mergedPrOptions(command2));
+  });
+  return command;
+}
+function createPrCommentsEditCommand() {
+  return buildCommentEditCommand("edit", "Edit an existing pull request comment in place");
+}
+function createPrCommentEditCommand() {
+  return buildCommentEditCommand(
+    "comment-edit",
+    'Edit an existing pull request comment in place (alias of "azdo pr comments edit")'
+  );
+}
+var LIST_STATUS_VALUES = ["active", "completed", "abandoned", "all"];
+var DEFAULT_LIST_TOP = 25;
+function formatPullRequestListEntry(pullRequest) {
+  return [
+    `#${pullRequest.id} [${pullRequest.status}] ${pullRequest.title}`,
+    `  ${formatBranchName(pullRequest.sourceRefName)} -> ${formatBranchName(pullRequest.targetRefName)}`,
+    `  Author: ${pullRequest.createdBy ?? "Unknown"}`,
+    `  ${pullRequest.url ?? "\u2014"}`
+  ].join("\n");
+}
+function createPrListCommand() {
+  const command = new Command12("list");
+  withCommonPrOptions(configureUnwrappedHelp(command)).description("List pull requests in the repository, optionally filtered by source branch").option("--branch <name>", "only pull requests whose source branch is this one (with or without the refs/heads/ prefix)").option("--status <status>", `pull request status filter (${LIST_STATUS_VALUES.join(" | ")})`, "active").option("--top <N>", `maximum number of pull requests to return (default ${DEFAULT_LIST_TOP})`).option("--json", "output JSON").action(async (options) => {
+    validateOrgProjectPair(options);
+    const status2 = options.status ?? "active";
+    if (!LIST_STATUS_VALUES.includes(status2)) {
+      writeError(`Invalid --status "${status2}"; expected one of ${LIST_STATUS_VALUES.join(", ")}.`);
+      return;
+    }
+    let top = DEFAULT_LIST_TOP;
+    if (options.top !== void 0) {
+      const parsed = parsePositivePrNumber(options.top);
+      if (parsed === null) {
+        writeError(`Invalid --top "${options.top}"; expected a positive integer.`);
+        return;
+      }
+      top = parsed;
+    }
+    const branch = options.branch?.trim().replace(/^refs\/heads\//, "") || null;
+    let context;
+    try {
+      const resolved = await resolvePrCommandContext(options, { requireBranch: false });
+      context = resolved.context;
+      const pullRequests = await listRepositoryPullRequests(resolved.context, resolved.repo, resolved.pat, {
+        sourceBranch: branch ?? void 0,
+        status: status2,
+        top
+      });
+      const result = {
+        repository: resolved.repo,
+        branch,
+        status: status2,
+        pullRequests
+      };
+      if (options.json) {
+        process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+        return;
+      }
+      if (pullRequests.length === 0) {
+        const branchSuffix = branch === null ? "" : ` for branch ${branch}`;
+        process.stdout.write(`No ${status2} pull request found in ${resolved.repo}${branchSuffix}.
+`);
+        return;
+      }
+      process.stdout.write(`${pullRequests.map(formatPullRequestListEntry).join("\n\n")}
+`);
+    } catch (err) {
+      handlePrCommandError(err, context, "read");
+    }
   });
   return command;
 }
 function createPrCommand() {
   const command = new Command12("pr");
   command.description("Manage Azure DevOps pull requests");
+  command.addCommand(createPrListCommand());
   command.addCommand(createPrStatusCommand());
   command.addCommand(createPrOpenCommand());
   command.addCommand(createPrCommentsCommand());
   command.addCommand(createPrCommentResolveCommand());
   command.addCommand(createPrCommentReopenCommand());
   command.addCommand(createPrCommentReplyCommand());
+  command.addCommand(createPrCommentAddCommand());
+  command.addCommand(createPrCommentEditCommand());
   return command;
 }
 
@@ -5040,7 +5592,7 @@ function createCommentsCommand() {
 // src/commands/download-attachment.ts
 import { Command as Command15 } from "commander";
 import { writeFile as writeFile2 } from "fs/promises";
-import { existsSync as existsSync5 } from "fs";
+import { existsSync as existsSync6 } from "fs";
 import { join as join3 } from "path";
 function createDownloadAttachmentCommand() {
   const command = new Command15("download-attachment");
@@ -5053,7 +5605,7 @@ function createDownloadAttachmentCommand() {
         context = resolveContext(options);
         const credential = await requireAuthCredential(context.org);
         const outputDir = options.output ?? ".";
-        if (!existsSync5(outputDir)) {
+        if (!existsSync6(outputDir)) {
           process.stderr.write(`Error: Output directory "${outputDir}" does not exist.
 `);
           process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "azdo-cli",
-  "version": "0.15.0-develop.593",
+  "version": "0.15.0-develop.604",
   "description": "Azure DevOps CLI tool",
   "type": "module",
   "bin": {