Add --debug flag for WebSocket connection diagnostics

Shows WS URL, auth headers (truncated), full handshake request/response.
Also improves the handshake failure error to include the raw server response.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

lib/portainer_cli/websocket_exec.rb

@@ -10,17 +10,23 @@ module PortainerCli
   class WebsocketExec
     READ_SIZE = 4096
 
-    def initialize(url, auth_header, ssl_verify: true)
+    def initialize(url, auth_header, ssl_verify: true, debug: false)
       @url         = URI.parse(url)
       @auth_header = auth_header
       @ssl_verify  = ssl_verify
+      @debug       = debug
     end
 
     def run
+      debug "WS URL: #{@url}"
+      debug "Auth headers: #{@auth_header.map { |k, v| "#{k}: #{v[0, 8]}..." }.join(', ')}"
+
       socket = open_socket
 
       handshake = perform_handshake(socket)
-      raise "WebSocket handshake failed: #{handshake.error}" unless handshake.valid?
+      unless handshake.valid?
+        raise "WebSocket handshake failed: #{handshake.error}\nServer response:\n#{handshake.instance_variable_get(:@data)}"
+      end
 
       run_io_loop(socket)
     ensure
@@ -50,18 +56,27 @@ module PortainerCli
         url:     @url.to_s,
         headers: @auth_header
       )
+      debug "Handshake request:\n#{handshake.to_s.chomp}"
       socket.write(handshake.to_s)
 
+      response = +''
       loop do
         byte = socket.read(1)
         break if byte.nil?
+        response << byte
         handshake << byte
         break if handshake.finished?
       end
+      debug "Handshake response:\n#{response.chomp}"
 
       handshake
     end
 
+    def debug(msg)
+      return unless @debug
+      $stderr.puts "\e[2m[debug] #{msg}\e[0m"
+    end
+
     def run_io_loop(socket)
       incoming = WebSocket::Frame::Incoming::Client.new