Bose-SoundTouch/docs/MERGE_PROJECTS.md

Merging Bose-SoundTouch-API into Bose-SoundTouch

This document outlines the plan to merge the Bose-SoundTouch-API project into this repository. The actual Go implementation in that repository is located in the soundcork-go subdirectory. The goal is to provide both a CLI (soundtouch-cli) and a service (soundtouch-service) from a single codebase.

Goals

• Maintain the existing soundtouch-cli functionality.
• Introduce soundtouch-service as a new command (based on the soundcork-go project).
• Consolidate shared logic (models, clients, discovery) into the pkg/ directory.
• Simplify maintenance by having a single Go module and shared CI/CD pipeline.

Current Directory Structure

.
├── cmd/
│   ├── soundtouch-cli/        # Existing CLI implementation
│   │   └── main.go
│   └── soundtouch-service/    # New service implementation (REST API / Websocket)
│       └── main.go
├── pkg/
│   ├── client/                # Shared SoundTouch API client
│   ├── models/                # Shared data models
│   ├── discovery/             # Shared device discovery logic
│   └── service/               # Service-specific logic (from Bose-SoundTouch-API)
│       ├── bmx/               # BMX service logic
│       ├── marge/             # Marge service logic
│       ├── datastore/         # Device and configuration storage
│       ├── proxy/             # Logging proxy logic
│       ├── setup/             # Device setup and migration logic
│       └── handlers/          # HTTP handlers (adapted from soundcork-go/soundcork-go)
│           └── soundcork/     # Embedded resources (index.html, media/, etc.)
├── docs/
│   └── MERGE_PROJECTS.md      # This document
├── go.mod
└── go.sum

Step-by-Step Merge Status

1. Preparation

• Review go.mod in both projects to identify dependency overlaps and conflicts.

2. Code Integration

• Models & Client: Merged missing functionality from soundcork-go/internal/models into pkg/models. Renamed overlapping models to Service* (e.g., ServiceContentItem, ServicePreset).
• Service Logic: Adapted internal packages from soundcork-go/internal/ to pkg/service/.
• Handlers: Moved and adapted HTTP handlers into pkg/service/handlers/.
• New Command: Created cmd/soundtouch-service/main.go as the service entry point using chi router.
• Embedded Resources: Integrated index.html, bmx_services.json, swupdate.xml, and media/ folder into the binary using //go:embed.

3. Dependency Management

• Update go.mod to include:
  • github.com/go-chi/chi/v5
  • github.com/srwiley/oksvg and github.com/srwiley/rasterx
  • golang.org/x/crypto
• Run go mod tidy to clean up dependencies.

4. Shared Logic Refactoring

• Identify common code between soundtouch-cli and the new service.
• Move shared logic into pkg/ to ensure both commands use the same underlying implementation.

5. Documentation & Examples

• Update README.md to mention the new soundtouch-service command.
• Add service-specific documentation in docs/SOUNDTOUCH-SERVICE.md.
• Provide examples of how to run and interact with the service in examples/service-demo/.

6. CI/CD Updates

• Update .github/workflows/release.yml to build and release the soundtouch-service binary alongside soundtouch-cli.
• Update any test workflows to include tests for the service logic.

Verification

• go build ./cmd/soundtouch-cli works as expected.
• go build ./cmd/soundtouch-service works as expected.
• All tests pass: go test ./....
• Resources are correctly served from the embedded filesystem.