yellowjacket/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project

YellowJacket is a cross-platform desktop music player built with Go (backend) and TypeScript/Lit (frontend), using the Wails framework to bridge them. It supports MP3, FLAC, OGG Vorbis, and WAV playback.

Planning

Active and historical plans live in .planning/:

• .planning/ROADMAP.md — vision, capability set, milestone sequence.
• .planning/NOTES.md — gotchas, deferred items, open architecture questions, the "we already considered and rejected" list.
• .planning/plans/active/ — work currently in progress (read first).
• .planning/plans/pending/ — sequenced future work.
• .planning/plans/completed/ — one concise recap per shipped milestone.

Numbering is sequential and stable across status moves (a plan keeps its NNN- prefix as it migrates between pending → active → completed). Abandoned plans are deleted; paused work stays in pending/.

The legacy .gsd/ directory is a snapshot of the prior GSD-CLI planning system. It's gitignored and will be removed once nothing relies on it.

Commands

make dev              # Hot-reload development (installs deps, generates code, cleans frontend)
make dev-debug        # Same as dev but with YJ_LOG_LEVEL=debug
make build-dev        # Debug build with symbols
make build-prod       # Production build (stripped, UPX-compressed)
make generate         # Run code generators (sqlc + templ via go generate)
make lint             # golangci-lint v2 (strict)
make test             # All tests with race detector, 2min timeout
make vulncheck        # govulncheck for CVEs
make setup            # Install go tools, frontend deps, git hooks (lefthook)

Running tests

All Go test commands require the -tags webkit2_41 build tag:

go test -tags webkit2_41 ./...                           # All tests
go test -tags webkit2_41 ./backend/player/               # Single package
go test -tags webkit2_41 -run TestName ./backend/player/  # Single test

Audio playback integration tests require YELLOWJACKET_INTEGRATION=1.

Architecture

Wails app lifecycle (main.go → backend/app.go): YellowJacketApp is the root struct bound to Wails. Its methods are callable from the frontend. Lifecycle hooks: OnStartup (init audio), OnDomReady (start library scan), OnBeforeClose (save window state), OnShutdown (persist player/queue state).

Backend packages (under backend/):

• player — Audio playback via beep. BufferedStreamer provides a ring buffer for smooth seeking.
• queue — Track queue with shuffle (Fisher-Yates), repeat modes, auto-advance, and session persistence.
• library — Concurrent library scanning, metadata extraction, cover art deduplication, incremental rescan.
• database — SQLite via pure-Go driver. Schema in database/sql/schemas/, queries in database/sql/queries/. sqlc generates Go code into database/sql/sqlcgen/ — never edit that directory by hand.
• metadata — Tag extraction (ID3v2, Vorbis Comments, FLAC).
• config — TOML-based settings. Settings page uses HTMX + templ for server-rendered HTML fragments.
• playlist / smartplaylist — Playlist CRUD and rule-based smart playlists.
• mediacontrols — MPRIS integration on Linux via D-Bus.
• system — OS-specific paths (XDG on Linux, %LOCALAPPDATA% on Windows).
• profiling — pprof server on :6060, compiled out in non-dev builds via build tags (internal/dev/).

Frontend (frontend/): Lit 3.2 web components + Web Awesome UI library + HTMX. State management via singleton reactive stores in src/store/. Wails bindings auto-generated in frontend/wailsjs/ — don't edit by hand.

Event-driven communication: Backend emits events via Wails runtime; frontend stores subscribe to them. Event names are constants in backend/events/.

Code Generation

Two generators run via go generate ./... (or make generate):

1. sqlc — SQL → Go. Config at backend/database/sqlc.yaml. Add queries in backend/database/sql/queries/, get generated Go in database/sql/sqlcgen/.
2. templ — .templ files → *_templ.go files (same directory).

Pre-commit hooks verify generated code is fresh — always run make generate after changing .sql or .templ files.

Code Style

• Go: golangci-lint v2 with strict linters including err113 (static errors), nlreturn, wsl_v5 (whitespace), godot (comment periods), sloglint, perfsprint. Imports grouped: stdlib → third-party → yellowjacket/... (enforced by gci).
• TypeScript: Strict mode, no implicit any, no unused locals/parameters.
• Commits: Conventional commits format (enforced by commitlint in CI). Semantic release uses these for versioning.

Testing

Tests use database.NewTestDB(t) for in-memory SQLite with full schema. Test audio fixtures live in test_data/music_library_test/. Table-driven tests are the norm.

Git Workflow

Direct push to main is blocked by lefthook — use feature branches and PRs. Pre-commit runs vet, lint, codegen check, and frontend typecheck in parallel. Pre-push runs the full test suite.