mirror of
https://github.com/gesellix/Bose-SoundTouch.git
synced 2026-08-19 00:56:16 +00:00
Tobias Gesellchen
ad43cdaf88
- Force IPv4-only mDNS queries with DisableIPv6=true to avoid routing issues - Add automatic IPv4 interface selection for better compatibility - Filter mDNS results to only include SoundTouch devices - Clean up device names by unescaping mDNS characters - Fix timeout flag handling to respect DISCOVERY_TIMEOUT from .env file - Only override discovery timeout when --timeout flag is explicitly provided - Add file operations safety guidelines to docs/CLAUDE.md - Remove duplicate timeout flags from discover command, use global flags Fixes IPv6 'no route to host' errors that prevented mDNS discovery. Now discovers same devices as native dns-sd and dig tools.
99 lines
4.1 KiB
Markdown
99 lines
4.1 KiB
Markdown
# CLAUDE.md - Development Guidelines for Bose SoundTouch Project
|
|
|
|
## Documentation Overview
|
|
|
|
This document contains important development guidelines for working on the Bose SoundTouch project. Please also read the following documentation:
|
|
|
|
- **[PLAN.md](PLAN.md)** - Project planning and roadmap
|
|
- **[PROJECT-PATTERNS.md](PROJECT-PATTERNS.md)** - Project structure and design patterns
|
|
- **[API-Endpoints-Overview.md](API-Endpoints-Overview.md)** - API endpoints overview
|
|
- **[SoundTouch Web API.pdf](2025.12.18%20SoundTouch%20Web%20API.pdf)** - Official API documentation
|
|
|
|
## Development Guidelines
|
|
|
|
### 1. Tests are Mandatory
|
|
|
|
- **Implementation always with tests**: Every new functionality must be developed with corresponding tests
|
|
- **Unit tests preferred**: Where possible, unit tests should be written
|
|
- **Integration tests as alternative**: If unit tests are not practical, implement integration tests via mock servers
|
|
- **Sample data from live system**: Request/response data can be taken from a real SoundTouch system as examples
|
|
- **Respect privacy**: All personal data must be anonymized before use in tests
|
|
|
|
### 2. Cross-Platform Compatibility
|
|
|
|
The project must work on the following platforms:
|
|
- **Windows**
|
|
- **macOS**
|
|
- **Linux**
|
|
- **WASM** (WebAssembly)
|
|
|
|
Platform-specific implementations are only allowed in justified exceptional cases.
|
|
|
|
### 3. KISS Principle (Keep It Simple, Stupid)
|
|
|
|
- Simplicity has top priority
|
|
- Complex solutions only when absolutely necessary
|
|
- Code should be self-explanatory and well readable
|
|
- Avoid over-engineering
|
|
|
|
### 4. Small Steps and Communication
|
|
|
|
- **Small, iterative steps**: Break large features into smaller, testable units
|
|
- **Don't hallucinate**: Don't make assumptions about unclear requirements
|
|
- **Ask instead of guess**: Always ask when unclear instead of speculating
|
|
- **Transparency**: Openly communicate uncertainties and limitations
|
|
|
|
### 5. Use Current Libraries
|
|
|
|
- Use current and well-maintained libraries where possible
|
|
- Regularly update outdated dependencies
|
|
- Apply security updates promptly
|
|
- Ensure compatibility with Go modules
|
|
|
|
### 6. Web-Specific Implementation
|
|
|
|
For web components:
|
|
- **Prefer plain HTML/JS/CSS**: Avoid heavy frameworks where possible
|
|
- Use modern web standards (ES6+, CSS Grid/Flexbox)
|
|
- Apply progressive enhancement
|
|
- Consider accessibility (a11y)
|
|
- Implement responsive design
|
|
|
|
## Build and Development Guidelines
|
|
|
|
### 7. Build Directory Structure
|
|
|
|
- **Use Makefile for building**: Always use `make build` instead of direct `go build` commands
|
|
- **Build directory**: All binaries must be created in the `./build/` directory
|
|
- **Example**: Use `make build` to create `./build/soundtouch-cli`, not `./soundtouch-cli`
|
|
- **Cross-platform builds**: Use `make build-all` for multi-platform binaries
|
|
|
|
### 8. Real Device Test Data
|
|
|
|
When creating test data for API endpoints, prefer real device responses over hypothetical examples:
|
|
|
|
- **Available test endpoints**:
|
|
- `http://192.168.178.28:8090/now_playing` - Different response type 1
|
|
- `http://192.168.178.35:8090/now_playing` - Different response type 2
|
|
- **Usage**: Fetch real responses to create accurate test fixtures
|
|
- **Privacy**: Anonymize any personal data (account names, personal playlists, etc.)
|
|
- **Coverage**: Use multiple real devices to cover different response variations
|
|
- **Non-responsive endpoints**: Some endpoints like `/trackInfo` may not respond or exist on all devices
|
|
|
|
### 9. File Operations Safety
|
|
|
|
- **Never delete files** - use move/rename instead when possible
|
|
- **Ask before destructive operations** - especially for config files (.env, *.config, etc.)
|
|
- **Prefer non-destructive operations** - copy, move, rename over delete
|
|
- **Respect user data** - treat all user files as potentially containing sensitive data
|
|
- **Configuration files are sacred** - .env, config files may contain secrets and personal settings
|
|
|
|
## Additional Notes
|
|
|
|
- **Language: English** for code, commits, labels, and text in code
|
|
- Code comments in English
|
|
- **Documentation**: Completely in English for international accessibility
|
|
- Conduct regular code reviews
|
|
- Consider performance from the beginning
|
|
|