Fix misleading error messages when Kubernetes configuration is missing

[Copilot]

Problem

Users running GitHub Actions workflows with Preevy's Kubernetes driver were getting misleading error messages that suggested tunnel server connectivity issues when the actual problem was missing or incorrect Kubernetes configuration. This made troubleshooting difficult, especially in CI/CD environments where users couldn't easily distinguish between tunnel server problems and Kubernetes cluster connectivity issues.

Solution

Enhanced the Kubernetes driver's error handling to detect common connectivity issues and provide clear, actionable error messages that explicitly identify them as Kubernetes-related problems.

Key Changes

Added KubernetesConnectionError class for Kubernetes-specific errors with enhanced messaging.

Improved error detection in the logError wrapper to identify and enhance:

• Connection refused errors (ECONNREFUSED) → Cluster unreachable
• DNS resolution failures (ENOTFOUND) → Hostname resolution issues
• Authentication errors (401) → Credential problems
• Authorization errors (403) → Permission issues
• Timeout errors → Network connectivity problems
• Configuration errors → Missing/invalid kubeconfig

Enhanced error messages that provide specific guidance and explicitly state:

"This is a Kubernetes connectivity issue, not a tunnel server problem."

Example

Before:

Cannot connect to ssh://tunnel.example.com:2222: connect ECONNREFUSED 10.0.0.1:6443

After:

Failed to connect to Kubernetes cluster. The Kubernetes API server appears to be unreachable. 
Please check that your cluster is running and accessible.

This is a Kubernetes connectivity issue, not a tunnel server problem.

Testing

• Added comprehensive unit and integration tests (30 total tests)
• All existing functionality preserved - non-connection errors pass through unchanged
• Verified error enhancement works for various failure scenarios
• Created demo script showing before/after error messages

Impact

• Improves user experience in GitHub Actions and CI environments
• Reduces confusion between tunnel server and Kubernetes issues
• Provides actionable guidance for troubleshooting cluster connectivity
• Maintains backward compatibility with existing error handling

Fixes the issue where users received misleading tunnel server error messages when Kubernetes configuration was missing or incorrect.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Bug]: Bad kubernetes configuration causes misleading error</issue_title>
<issue_description>### What happened?

My GitHub Actions workflow was missing the k8s config, but the error made it look like something was wrong with the tunnel server.

Add screenshots

Steps to reproduce the behavior

Set up a GHA workflow with a preevy profile using kubernetes, but don't add any configuration for the kubernetes client.

Expected behavior

Expected an error that indicated a connection problem with kubernetes rather than with the tunnel server.

What OS are you seeing the problem on?

No response

Additional context

No response

Record

• I agree to follow this project's Code of Conduct</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes #457

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.