yonlu
6ce0661fca
Archive milestone artifacts: - milestones/v1.0-ROADMAP.md (full roadmap archive) - milestones/v1.0-REQUIREMENTS.md (26/26 requirements complete) - milestones/v1.0-phases/ (8 phase directories with plans, summaries, verifications) Updated: - PROJECT.md: full evolution review, all consolidation requirements validated - ROADMAP.md: collapsed to milestone summary with archive link - STATE.md: reset for next milestone - MILESTONES.md: created with stats and accomplishments - RETROSPECTIVE.md: created with lessons learned Deleted: - REQUIREMENTS.md (archived, fresh for next milestone) 8 phases, 17 plans, 34 tasks, 84 tests added, 6 days
105 lines
6.7 KiB
Markdown
105 lines
6.7 KiB
Markdown
# YellowJacket
|
|
|
|
## What This Is
|
|
|
|
YellowJacket is a cross-platform desktop music player built with Go (Wails v2) and TypeScript (Lit Web Components). It plays local music files (MP3, FLAC, OGG, WAV), manages a music library via SQLite, and provides queue management, playlists, cover art, and MPRIS media controls on Linux. The v1.0 Consolidation milestone strengthened the foundation — all known concurrency races are fixed, error handling is honest, SQL patterns are consolidated, performance bottlenecks are resolved, the frontend follows a consistent design language, and 84 unit tests provide a safety net for future work.
|
|
|
|
## Core Value
|
|
|
|
The music player works reliably and feels solid. Every interaction is correct, responsive, and trustworthy — the foundation that all future features will build on.
|
|
|
|
## Requirements
|
|
|
|
### Validated
|
|
|
|
- ✓ Audio playback (play, pause, stop, seek, volume) for MP3, FLAC, OGG, WAV — existing
|
|
- ✓ Library scanning with concurrent metadata extraction pipeline — existing
|
|
- ✓ Queue management with shuffle, repeat modes, and auto-advance — existing
|
|
- ✓ Queue and player state persistence across app restarts — existing
|
|
- ✓ Full-text search across tracks, artists, albums, file paths (FTS5) — existing
|
|
- ✓ Playlist CRUD with M3U8 import/export and phantom track resolution — existing
|
|
- ✓ Favorites system with dedicated playlist — existing
|
|
- ✓ Cover art extraction, thumbnail generation (sm/md/lg), and serving — existing
|
|
- ✓ MPRIS2 media controls on Linux — existing
|
|
- ✓ Theme configuration (accent color, background shade) — existing
|
|
- ✓ Track list column configuration — existing
|
|
- ✓ Multiple library directory support — existing
|
|
- ✓ Adaptive scan concurrency based on disk type (SSD vs HDD) — existing
|
|
- ✓ Two-phase queue initialization for instant UI response — existing
|
|
- ✓ Event-driven frontend/backend synchronization — existing
|
|
- ✓ TOML-based user configuration with live reload — existing
|
|
- ✓ Browse by albums, artists, genres with detail views — existing
|
|
- ✓ Virtual scrolling for large lists — existing
|
|
- ✓ Concurrency race-free SetContext across Queue, Library, Playlist, Player — v1.0
|
|
- ✓ Error handling: startupErr moved to struct, config 0o644, MPRIS errors logged, scan warnings separated — v1.0
|
|
- ✓ FTS5 JOIN pattern consolidated into track_metadata VIEW — v1.0
|
|
- ✓ Event name codegen (Go→TypeScript) with pre-commit hook enforcement — v1.0
|
|
- ✓ Queue batch lookups use sqlc.slice(), all hand-crafted SQL documented with SAFETY comments — v1.0
|
|
- ✓ Incremental queue persistence (O(1) add/remove) and SetQueue Phase 2 dedup — v1.0
|
|
- ✓ Library store deferred loading for instant app shell — v1.0
|
|
- ✓ SQLite performance PRAGMAs (synchronous, cache_size, mmap_size) — v1.0
|
|
- ✓ Frontend repeat() with stable keys, queueMicrotask coalescing, classMap directives — v1.0
|
|
- ✓ Design token system and visual consistency across all 15 components — v1.0
|
|
- ✓ 84 unit tests: queue (29), config/player (10+), FTS5 search (15), library scan (13), entity cache (13+) — v1.0
|
|
|
|
### Active
|
|
|
|
(No active requirements — next milestone not yet scoped. Run `/gsd-new-milestone` to define.)
|
|
|
|
### Out of Scope
|
|
|
|
- Tag writing (track metadata editing) — feature work, not consolidation
|
|
- Scan cancellation — feature work, deferred to future milestone
|
|
- Cross-platform media controls (macOS/Windows) — feature work
|
|
- Database health checking / reconnection — low priority, desktop app context
|
|
- File decomposition for its own sake — only extract when it enables reuse or fixes problems
|
|
- ORM or query builder — would fight existing sqlc architecture
|
|
- Connection pooling for SQLite — meaningless with SetMaxOpenConns(1)
|
|
|
|
## Context
|
|
|
|
**Current state (v1.0 shipped 2026-03-05):**
|
|
- Go 1.25, Wails v2.10.2, Lit 3.2.1, SQLite via modernc.org/sqlite
|
|
- ~22,450 Go LOC + ~28,600 TypeScript LOC + ~5,200 Go test LOC
|
|
- ~15 backend packages, ~20 frontend components
|
|
- Strict linting (golangci-lint v2) and TypeScript strict mode
|
|
- 84 unit tests covering queue, config, player, database, library packages
|
|
- All concurrency races fixed, app runs clean under `-race`
|
|
- SQL consolidated: track_metadata VIEW, sqlc.slice(), SAFETY comments
|
|
- Frontend: design token system, virtual scrolling with stable keys, debounced store notifications
|
|
- Player tests still require hardware (skipped in CI)
|
|
- No frontend unit tests (deferred to v2)
|
|
|
|
**Codebase analysis available in:**
|
|
- `.planning/codebase/ARCHITECTURE.md`
|
|
- `.planning/codebase/CONCERNS.md`
|
|
- `.planning/codebase/CONVENTIONS.md`
|
|
- `.planning/codebase/INTEGRATIONS.md`
|
|
- `.planning/codebase/STACK.md`
|
|
|
|
## Constraints
|
|
|
|
- **Tech stack**: Go + Wails v2 + Lit + SQLite — no changes to the fundamental stack
|
|
- **Build tags**: All Go commands require `-tags webkit2_41` on Linux
|
|
- **Single writer**: SQLite with WAL mode and `SetMaxOpenConns(1)` — design around this
|
|
- **Backward compatibility**: Existing user config and database must continue working after changes
|
|
- **Linting**: All code must pass `make lint` (golangci-lint v2 with strict rules)
|
|
- **No CGo**: Pure-Go SQLite driver (`modernc.org/sqlite`) — cannot switch to CGo-based drivers
|
|
|
|
## Key Decisions
|
|
|
|
| Decision | Rationale | Outcome |
|
|
|----------|-----------|---------|
|
|
| Consolidation before features | Technical debt compounds — fixing it now is cheaper than fixing it later under more code | ✓ Good — solid foundation established |
|
|
| Tests support refactoring, not standalone goal | Testing is a means to safe refactoring, not a coverage target | ✓ Good — 84 tests enabled safe SQL and perf refactoring |
|
|
| No cosmetic file splitting | Large files are only a problem if they cause real issues; extract only for reuse or correctness | ✓ Good — avoided unnecessary churn |
|
|
| All improvement areas equal priority | Correctness, performance, code quality, UX, and testing are interdependent | ✓ Good — balanced approach worked well |
|
|
| Fix races → tests → refactoring order | Can't run `-race`-clean tests with active data races; can't safely refactor without tests | ✓ Good — each phase built on the last |
|
|
| SQLite VIEW for JOIN dedup | track_metadata VIEW consolidates 5-table JOIN; migration keeps inline for upgrade | ✓ Good — 60 lines eliminated, tests unchanged |
|
|
| AST-based event codegen | Deterministic declaration-order output, no regex fragility | ✓ Good — found LibraryConfigChanged gap automatically |
|
|
| queueMicrotask over setTimeout | Synchronous microtask batching is more predictable than macrotask scheduling | ✓ Good — coalesces 8+ notifications per scan |
|
|
| Design tokens via :host scope | Component-level token scope matches Lit's shadow DOM encapsulation | ✓ Good — consistent visual language achieved |
|
|
|
|
---
|
|
*Last updated: 2026-03-05 after v1.0 milestone*
|