feat(group): add ST-10 stereo-pair support end-to-end

Implements the speaker-side group API surface (path 1 of the two
approaches gmuth outlined in issue #252): clients form, rename, and
dissolve stereo pairs directly on the device, and the resulting
GroupService.xml persists on disk in the same shape the device emits
over /getGroup.

What landed:

- pkg/models/group.go: Status field + IsEmpty() helper, matching the
  GET /getGroup response shape (id-attr, masterDeviceId, roles,
  senderIPAddress).
- pkg/client/client.go: GetGroup, AddGroup, UpdateGroup, RemoveGroup.
  The endpoint name is /getGroup (not /group, despite some wiki docs)
  — confirmed against a real ST-10's /supportedURLs. RemoveGroup uses
  GET per the wire spec.
- cmd/soundtouch-cli/cmd_group.go + main.go: new `group` subcommand
  with status / create --left --right [--name] / rename / remove,
  mirroring gmuth's group.sh recipe.

WebSocket notifications:

- pkg/models/websocket.go: EventTypeGroupUpdated +
  GroupUpdatedEvent + dispatch helpers. The device fans this out to
  both LEFT and RIGHT speakers on every group mutation, including
  empty-group teardowns; the parse test covers both shapes.
- pkg/client/websocket.go: OnGroupUpdated registration and dispatch.
- cmd/soundtouch-cli/cmd_events.go: `group` filter +
  handleGroupEvent formatter.

WebSocket observability (came up while validating the above against
a real device):

- New RawMessageHandler type + OnRawMessage hook that fires for every
  incoming frame before parsing, with the parse error alongside.
- New --debug flag on `events subscribe` with modes all / unknown /
  errors. Raw output goes to stderr so it composes cleanly with
  shell redirects.

The pkg/client refactor in this commit also adopts speaker.HTTPPort
(introduced in the previous refactor) — the unexported
defaultSoundTouchPort and three hard-coded 8090 literals are gone.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

pkg/models/websocket.go

@@ -21,6 +21,10 @@ const (
 	EventTypePresetUpdated WebSocketEventType = "presetsUpdated"
 	// EventTypeZoneUpdated indicates a zone configuration change
 	EventTypeZoneUpdated WebSocketEventType = "zoneUpdated"
+	// EventTypeGroupUpdated is emitted to both ROLE devices when an ST-10
+	// stereo pair is created, renamed, or removed via /addGroup,
+	// /updateGroup, or /removeGroup.
+	EventTypeGroupUpdated WebSocketEventType = "groupUpdated"
 	// EventTypeBassUpdated indicates a bass level change
 	EventTypeBassUpdated WebSocketEventType = "bassUpdated"
 	// EventTypeClockTimeUpdated indicates a clock time change
@@ -56,6 +60,8 @@ func (e WebSocketEventType) String() string {
 		return "Preset Updated"
 	case EventTypeZoneUpdated:
 		return "Zone Updated"
+	case EventTypeGroupUpdated:
+		return "Stereo Pair Updated"
 	case EventTypeBassUpdated:
 		return "Bass Updated"
 	case EventTypeClockTimeUpdated:
@@ -88,6 +94,7 @@ type WebSocketEvent struct {
 	ConnectionStateUpdated *ConnectionStateUpdatedEvent `xml:"connectionStateUpdated,omitempty"`
 	PresetUpdated          *PresetUpdatedEvent          `xml:"presetsUpdated,omitempty"`
 	ZoneUpdated            *ZoneUpdatedEvent            `xml:"zoneUpdated,omitempty"`
+	GroupUpdated           *GroupUpdatedEvent           `xml:"groupUpdated,omitempty"`
 	BassUpdated            *BassUpdatedEvent            `xml:"bassUpdated,omitempty"`
 	ClockTimeUpdated       *ClockTimeUpdatedEvent       `xml:"clockTimeUpdated,omitempty"`
 	ClockDisplayUpdated    *ClockDisplayUpdatedEvent    `xml:"clockDisplayUpdated,omitempty"`
@@ -122,6 +129,10 @@ func (e *WebSocketEvent) GetEvents() []interface{} {
 		events = append(events, e.ZoneUpdated)
 	}
 
+	if e.GroupUpdated != nil {
+		events = append(events, e.GroupUpdated)
+	}
+
 	if e.BassUpdated != nil {
 		events = append(events, e.BassUpdated)
 	}
@@ -215,6 +226,16 @@ type ZoneUpdatedEvent struct {
 	Zone     Zone     `xml:"zone"`
 }
 
+// GroupUpdatedEvent represents an ST-10 stereo-pair update notification.
+// The device fans this event out to both LEFT and RIGHT speakers whenever
+// the pair is created, renamed, or removed. Group will be the zero value
+// for a teardown notification — see (*Group).IsEmpty.
+type GroupUpdatedEvent struct {
+	XMLName  xml.Name `xml:"groupUpdated"`
+	DeviceID string   `xml:"deviceID,attr"`
+	Group    Group    `xml:"group"`
+}
+
 // Zone represents multiroom zone information
 type Zone struct {
 	XMLName xml.Name     `xml:"zone"`
@@ -373,6 +394,7 @@ type WebSocketEventHandlers struct {
 	OnConnectionState     TypedEventHandler[*ConnectionStateUpdatedEvent]
 	OnPresetUpdated       TypedEventHandler[*PresetUpdatedEvent]
 	OnZoneUpdated         TypedEventHandler[*ZoneUpdatedEvent]
+	OnGroupUpdated        TypedEventHandler[*GroupUpdatedEvent]
 	OnBassUpdated         TypedEventHandler[*BassUpdatedEvent]
 	OnClockTimeUpdated    TypedEventHandler[*ClockTimeUpdatedEvent]
 	OnClockDisplayUpdated TypedEventHandler[*ClockDisplayUpdatedEvent]
@@ -382,8 +404,19 @@ type WebSocketEventHandlers struct {
 	OnLanguageUpdated     TypedEventHandler[*LanguageUpdatedEvent]
 	OnUnknownEvent        EventHandler
 	OnSpecialMessage      SpecialMessageHandler
+	// OnRawMessage fires for every received frame before any parsing
+	// happens. Use it for debug/observability tooling that wants to see
+	// exactly what the device sent on the wire — the typed handlers
+	// above still run afterwards, independently. parseErr is the result
+	// of the XML parse: nil for messages that decoded cleanly, non-nil
+	// for malformed payloads. The slice is owned by the caller; copy
+	// before retaining.
+	OnRawMessage RawMessageHandler
 }
 
+// RawMessageHandler defines the signature for raw-frame handlers.
+type RawMessageHandler func(data []byte, parseErr error)
+
 // ParseWebSocketEvent attempts to parse a WebSocket message into a specific event type
 func ParseWebSocketEvent(data []byte) (*WebSocketEvent, error) {
 	var event WebSocketEvent
@@ -411,6 +444,8 @@ func (e *WebSocketEvent) getFieldByEventType(eventType WebSocketEventType) inter
 		field = e.PresetUpdated
 	case EventTypeZoneUpdated:
 		field = e.ZoneUpdated
+	case EventTypeGroupUpdated:
+		field = e.GroupUpdated
 	case EventTypeBassUpdated:
 		field = e.BassUpdated
 	case EventTypeClockTimeUpdated:
@@ -462,6 +497,8 @@ func isNil(i interface{}) bool {
 		return v == nil
 	case *ZoneUpdatedEvent:
 		return v == nil
+	case *GroupUpdatedEvent:
+		return v == nil
 	case *BassUpdatedEvent:
 		return v == nil
 	case *ClockTimeUpdatedEvent:
@@ -508,6 +545,8 @@ func (e *WebSocketEvent) HasEventType(eventType WebSocketEventType) bool {
 		return e.PresetUpdated != nil
 	case EventTypeZoneUpdated:
 		return e.ZoneUpdated != nil
+	case EventTypeGroupUpdated:
+		return e.GroupUpdated != nil
 	case EventTypeBassUpdated:
 		return e.BassUpdated != nil
 	case EventTypeClockTimeUpdated:
@@ -551,6 +590,10 @@ func (e *WebSocketEvent) GetEventTypes() []WebSocketEventType {
 		types = append(types, EventTypeZoneUpdated)
 	}
 
+	if e.GroupUpdated != nil {
+		types = append(types, EventTypeGroupUpdated)
+	}
+
 	if e.BassUpdated != nil {
 		types = append(types, EventTypeBassUpdated)
 	}