fix(error-handling): improve network error diagnostics and lock timeout messages

- Enhanced HTTP request/download error handling with specific network diagnostics (ENOTFOUND, ECONNREFUSED, ETIMEDOUT, ECONNRESET)
- Improved download lock timeout error to include PID tracking, lock age, resource URL, and actionable resolution steps
- All error messages now provide clear context and guidance for troubleshooting

Author: jdalton

src/download-lock.ts

@@ -121,8 +121,16 @@ async function acquireLock(
         } else {
           // Lock is valid, check timeout
           if (Date.now() - startTime > lockTimeout) {
+            const lockAge = Date.now() - lockInfo.startTime
             throw new Error(
-              `Lock acquisition timed out after ${lockTimeout}ms (held by PID ${lockInfo.pid})`,
+              `Download lock timed out after ${lockTimeout}ms\n` +
+                `Lock held by process ${lockInfo.pid} for ${lockAge}ms\n` +
+                `Resource: ${lockInfo.url}\n` +
+                `Started: ${new Date(lockInfo.startTime).toISOString()}\n` +
+                'To resolve:\n' +
+                `  1. Check if process ${lockInfo.pid} is still running: ps -p ${lockInfo.pid}\n` +
+                `  2. If stale, remove lock file: rm "${lockPath}"\n` +
+                '  3. Or increase lockTimeout option',
             )
           }
 

src/http-request.ts

@@ -601,10 +601,27 @@ async function httpRequestAttempt(
     )
 
     request.on('error', (error: Error) => {
-      const err = new Error(`HTTP request failed: ${error.message}`, {
-        cause: error,
-      })
-      reject(err)
+      const code = (error as NodeJS.ErrnoException).code
+      let message = `HTTP request failed for ${url}: ${error.message}\n`
+
+      if (code === 'ENOTFOUND') {
+        message +=
+          'DNS lookup failed. Check the hostname and your network connection.'
+      } else if (code === 'ECONNREFUSED') {
+        message +=
+          'Connection refused. Verify the server is running and accessible.'
+      } else if (code === 'ETIMEDOUT') {
+        message +=
+          'Request timed out. Check your network or increase the timeout value.'
+      } else if (code === 'ECONNRESET') {
+        message +=
+          'Connection reset. The server may have closed the connection unexpectedly.'
+      } else {
+        message +=
+          'Check your network connection and verify the URL is correct.'
+      }
+
+      reject(new Error(message, { cause: error }))
     })
 
     request.on('timeout', () => {
@@ -811,10 +828,27 @@ async function httpDownloadAttempt(
 
     request.on('error', (error: Error) => {
       closeStream()
-      const err = new Error(`HTTP download failed: ${error.message}`, {
-        cause: error,
-      })
-      reject(err)
+      const code = (error as NodeJS.ErrnoException).code
+      let message = `HTTP download failed for ${url}: ${error.message}\n`
+
+      if (code === 'ENOTFOUND') {
+        message +=
+          'DNS lookup failed. Check the hostname and your network connection.'
+      } else if (code === 'ECONNREFUSED') {
+        message +=
+          'Connection refused. Verify the server is running and accessible.'
+      } else if (code === 'ETIMEDOUT') {
+        message +=
+          'Request timed out. Check your network or increase the timeout value.'
+      } else if (code === 'ECONNRESET') {
+        message +=
+          'Connection reset. The server may have closed the connection unexpectedly.'
+      } else {
+        message +=
+          'Check your network connection and verify the URL is correct.'
+      }
+
+      reject(new Error(message, { cause: error }))
     })
 
     request.on('timeout', () => {