feat: modernize API, fix critical bugs, and add test suite

[leandrodaf]

Summary

Complete modernization of the MIDI library: critical bug fixes, API redesign, and a new test suite (37 tests).

---

Bug Fixes

Darwin deadlock (critical)

StartCapture held mu.Lock() and called Stop(), which tried to re-acquire the same lock → deadlock. Fixed with stopLocked() pattern: Stop() acquires lock → calls stopLocked() → releases lock → calls wg.Wait() outside the lock.

sync.Once preventing restart

stopOnce sync.Once meant after the first Stop(), the client could never stop again after a restart. Replaced with a simple capturing bool guard.

Goroutine leak in CoreMIDI NewDestination

The processIncomingPacket goroutine was started before MIDIDestinationCreate. On failure, writeFd was never closed → goroutine blocked forever. Fixed: close writeFd on creation failure.

Windows syscall error handling

windows.NewLazySystemDLL proc.Call() always returns a non-nil err (it is Win32 GetLastError, not a Go error). Fixed: only use r1 != 0 as the error indicator.

fmt.Errorf throughout coremidi

All errors.New(fmt.Sprintf(...)) replaced with fmt.Errorf(...).

---

API Changes (breaking)

Field → plain struct

Field was a confusing interface that doubled as both a type and a builder. Now it's a plain struct { Key string; Value any } with standalone constructors:

contracts.IntField("deviceID", id)
contracts.ErrField("error", err)
contracts.StringField("name", name)
// etc.

StartCapture signature

// Before
StartCapture(eventChannel chan MIDI)

// After
StartCapture(ctx context.Context) (<-chan MIDI, error)

The client now creates and owns the channel. Cancelling the context triggers Stop() and closes the channel automatically.

New options

• WithChannelBufferSize(n int) — configure event channel buffer (default: 100)
• WithLogDestination(dest, filePath...) — route logs to console or file

LogLevel fix

InfoLevel = iota = 0 caused the default check to be ambiguous. Added logLevelSet bool + LogLevelIsSet(). LogLevel ordering corrected: Debug < Info < Warn < Error < Fatal.

contracts.IsCommandAllowed

Extracted from identical duplications in both darwin and windows clients. Handles nil filter internally.

dummyMIDIClient unexported

The cross-platform stub was exported unnecessarily.

---

Logger Rewrite

Replaced the uber-zap dependency with a lightweight stdLogger that writes structured lines with JSON fields. Same contracts.Logger interface — drop-in replacement. Added NewLoggerWithWriter(w io.Writer) for testability.

---

Test Suite (37 tests, all passing)

File	Tests
sdk/contracts/filter_test.go	IsCommandAllowed — nil filter, empty list, present, absent, multiple (5)
sdk/contracts/mock_test.go	MockMIDIClient — configured funcs, zero defaults, call counters (3)
sdk/midi/options_setup_test.go	applyDefaultOptions — defaults, overrides, LogLevelIsSet (8)
internal/logger/logger_wrapper_test.go	Level filtering, field output, SetLevel, SetDestination (9)

Also added sdk/contracts/mock.go — a MockMIDIClient for library consumers to use in their own tests.

---

Files Changed

• 31 files changed, 1821 insertions(+), 556 deletions(-)