fix(issue-list): propagate ApiError instead of plain Error on fetch failures

When all project fetches fail, re-throw the original ApiError (with
status, detail, endpoint) instead of a plain Error. This lets the
telemetry layer in PR #251 correctly classify 4xx errors as client
errors and suppress them from Sentry exceptions.

Also:
- Classify more HTTP status codes (404, 429, other 4xx) instead of
  lumping everything into "unknown"
- Include partial failure info in JSON output when some projects fail
- Warn on stderr about partial failures in human output
- Add tests for error propagation and partial failure handling

Author: BYK

src/commands/issue/list.ts

@@ -53,7 +53,36 @@ const VALID_SORT_VALUES: SortValue[] = ["date", "new", "freq", "user"];
 const USAGE_HINT = "sentry issue list <org>/<project>";
 
 /** Error type classification for fetch failures */
-type FetchErrorType = "permission" | "network" | "unknown";
+type FetchErrorType =
+  | "permission"
+  | "not_found"
+  | "rate_limit"
+  | "bad_request"
+  | "network"
+  | "unknown";
+
+/**
+ * Classify an API error by HTTP status code for user-facing messaging.
+ *
+ * @param error - The ApiError to classify
+ * @returns Error type classification
+ */
+function classifyApiError(error: ApiError): FetchErrorType {
+  const { status } = error;
+  if (status === 401 || status === 403) {
+    return "permission";
+  }
+  if (status === 404) {
+    return "not_found";
+  }
+  if (status === 429) {
+    return "rate_limit";
+  }
+  if (status >= 400 && status < 500) {
+    return "bad_request";
+  }
+  return "unknown";
+}
 
 function parseSort(value: string): SortValue {
   if (!VALID_SORT_VALUES.includes(value as SortValue)) {
@@ -241,7 +270,7 @@ function getComparator(
 
 type FetchResult =
   | { success: true; data: IssueListResult }
-  | { success: false; errorType: FetchErrorType };
+  | { success: false; errorType: FetchErrorType; error: Error };
 
 /** Result of resolving targets from parsed argument */
 type TargetResolutionResult = {
@@ -364,19 +393,24 @@ async function fetchIssuesForTarget(
     if (error instanceof AuthError) {
       throw error;
     }
-    // Classify error type for better user messaging
-    // 401/403 are permission errors
-    if (
-      error instanceof ApiError &&
-      (error.status === 401 || error.status === 403)
-    ) {
-      return { success: false, errorType: "permission" };
+
+    const wrapped = error instanceof Error ? error : new Error(String(error));
+
+    // Classify API errors by status code for targeted user messaging
+    if (error instanceof ApiError) {
+      return {
+        success: false,
+        errorType: classifyApiError(error),
+        error: wrapped,
+      };
     }
+
     // Network errors (fetch failures, timeouts)
     if (error instanceof TypeError && error.message.includes("fetch")) {
-      return { success: false, errorType: "network" };
+      return { success: false, errorType: "network", error: wrapped };
     }
-    return { success: false, errorType: "unknown" };
+
+    return { success: false, errorType: "unknown", error: wrapped };
   }
 }
 
@@ -438,7 +472,7 @@ export const listCommand = buildCommand({
     flags: ListFlags,
     target?: string
   ): Promise<void> {
-    const { stdout, cwd, setContext } = this;
+    const { stdout, stderr, cwd, setContext } = this;
 
     // Parse positional argument to determine resolution strategy
     const parsed = parseOrgProjectArg(target);
@@ -477,34 +511,36 @@ export const listCommand = buildCommand({
 
     // Separate successful fetches from failures
     const validResults: IssueListResult[] = [];
-    const errorTypes = new Set<FetchErrorType>();
+    const failures: { errorType: FetchErrorType; error: Error }[] = [];
 
     for (const result of results) {
       if (result.success) {
         validResults.push(result.data);
       } else {
-        errorTypes.add(result.errorType);
+        failures.push({ errorType: result.errorType, error: result.error });
       }
     }
 
-    if (validResults.length === 0) {
-      // Build error message based on what types of errors we saw
-      if (errorTypes.has("permission")) {
-        throw new Error(
-          `Failed to fetch issues from ${targets.length} project(s).\n` +
-            "You don't have permission to access these projects.\n\n" +
-            "Try running 'sentry auth status' to verify your authentication."
+    if (validResults.length === 0 && failures.length > 0) {
+      // Re-throw the first underlying error so telemetry can classify it
+      // correctly (e.g., ApiError → isClientApiError → suppressed from exceptions).
+      // Add context about how many projects failed.
+      // biome-ignore lint/style/noNonNullAssertion: guarded by failures.length > 0
+      const first = failures[0]!;
+      const prefix = `Failed to fetch issues from ${targets.length} project(s)`;
+
+      // For ApiError, propagate the original so telemetry sees the status code
+      if (first.error instanceof ApiError) {
+        throw new ApiError(
+          `${prefix}: ${first.error.message}`,
+          first.error.status,
+          first.error.detail,
+          first.error.endpoint
         );
       }
-      if (errorTypes.has("network")) {
-        throw new Error(
-          `Failed to fetch issues from ${targets.length} project(s).\n` +
-            "Network connection failed. Check your internet connection."
-        );
-      }
-      throw new Error(
-        `Failed to fetch issues from ${targets.length} project(s).`
-      );
+
+      // For other errors, add context to the message
+      throw new Error(`${prefix}.\n${first.error.message}`);
     }
 
     // Determine display mode
@@ -539,13 +575,32 @@ export const listCommand = buildCommand({
       getComparator(flags.sort)(a.issue, b.issue)
     );
 
-    // JSON output
+    // JSON output — include partial failure info when some projects failed
     if (flags.json) {
       const allIssues = issuesWithOptions.map((i) => i.issue);
-      writeJson(stdout, allIssues);
+      if (failures.length > 0) {
+        writeJson(stdout, {
+          issues: allIssues,
+          errors: failures.map((f) => ({
+            type: f.errorType,
+            message: f.error.message,
+          })),
+        });
+      } else {
+        writeJson(stdout, allIssues);
+      }
       return;
     }
 
+    // Warn on stderr about partial failures (human output only)
+    if (failures.length > 0) {
+      stderr.write(
+        muted(
+          `\nNote: Failed to fetch issues from ${failures.length} project(s). Showing results from ${validResults.length} project(s).\n`
+        )
+      );
+    }
+
     if (issuesWithOptions.length === 0) {
       stdout.write("No issues found.\n");
       if (footer) {