Treat transient network errors as AbortError instead of BugError

Renames isARetryableNetworkError to isTransientNetworkError for clarity
and exports it for reuse in fetchApiVersions error handling. This fixes
6,941+ production errors that were incorrectly classified as bugs.

Changes:
- Renamed isARetryableNetworkError -> isTransientNetworkError
- Added JSDoc explaining these are transient network errors
- Exported function for reuse across the codebase
- Enhanced detection patterns to include TLS/cert errors, premature close, timeouts
- Updated fetchApiVersions to classify network errors as AbortError

Network errors now properly classified include:
- TLS certificate validation failures (main issue with 6,941 occurrences)
- Connection timeouts (ETIMEDOUT)
- Connection resets (ECONNRESET)
- DNS failures (ENOTFOUND, getaddrinfo)
- Socket disconnects and premature closes

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: amcaplan

.changeset/network-errors-as-abort-errors.md

@@ -0,0 +1,5 @@
+---
+'@shopify/cli-kit': patch
+---
+
+Treat transient network errors as user-facing AbortError instead of BugError in fetchApiVersions

packages/cli-kit/src/private/node/api.ts

@@ -68,7 +68,13 @@ type VerboseResponse<T> =
   | CanRetryErrorResponse
   | UnauthorizedErrorResponse
 
-function isARetryableNetworkError(error: unknown): boolean {
+/**
+ * Checks if an error is a transient network error (connection issues, timeouts, DNS failures, TLS errors, etc.)
+ * rather than an application logic error. These errors are typically:
+ * - Worth retrying (when retry logic is configured)
+ * - Should be reported as user-facing errors (AbortError) rather than bugs (BugError)
+ */
+export function isTransientNetworkError(error: unknown): boolean {
   if (error instanceof Error) {
     const networkErrorMessages = [
       'socket hang up',
@@ -82,6 +88,14 @@ function isARetryableNetworkError(error: unknown): boolean {
       'eai_again',
       'epipe',
       'the operation was aborted',
+      'timeout',
+      'premature close',
+      'certificate',
+      'cert',
+      'tls',
+      'ssl',
+      'altnames',
+      'getaddrinfo',
     ]
     const errorMessage = error.message.toLowerCase()
     const anyMatches = networkErrorMessages.some((issueMessage) => errorMessage.includes(issueMessage))
@@ -105,7 +119,7 @@ async function runRequestWithNetworkLevelRetry<T extends {headers: Headers; stat
       return await requestOptions.request()
     } catch (err) {
       lastSeenError = err
-      if (!isARetryableNetworkError(err)) {
+      if (!isTransientNetworkError(err)) {
         throw err
       }
       outputDebug(`Retrying request to ${requestOptions.url} due to network error ${err}`)

packages/cli-kit/src/public/node/api/admin.ts

@@ -14,6 +14,7 @@ import {
   restRequestUrl,
   isThemeAccessSession,
 } from '../../../private/node/api/rest.js'
+import {isTransientNetworkError} from '../../../private/node/api.js'
 import {RequestModeInput, shopifyFetch} from '../http.js'
 import {PublicApiVersions} from '../../../cli/api/graphql/admin/generated/public_api_versions.js'
 
@@ -182,13 +183,25 @@ async function fetchApiVersions(session: AdminSession, preferredBehaviour?: Requ
       throw new AbortError(
         `Error connecting to your store ${session.storeFqdn}: ${error.message} ${error.response.status} ${error.response.data}`,
       )
-    } else {
-      throw new BugError(
-        `Unknown error connecting to your store ${session.storeFqdn}: ${
+    }
+
+    // Check for network-level errors (connection issues, timeouts, DNS failures, TLS errors, etc.)
+    // These are transient errors that may have been retried already by lower-level retry logic
+    if (isTransientNetworkError(error)) {
+      throw new AbortError(
+        `Network error connecting to your store ${session.storeFqdn}: ${
           error instanceof Error ? error.message : String(error)
         }`,
+        'Check your internet connection and try again.',
       )
     }
+
+    // Unknown errors are likely bugs in the CLI
+    throw new BugError(
+      `Unknown error connecting to your store ${session.storeFqdn}: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    )
   }
 }