File-based logging with intent-based applog facade (#192)

* feat: file-based logging with intent-based applog facade

Closes #176.

Adds a slog-backed file logger at ~/.config/cliamp/cliamp.log with a
configurable level (log_level config key, --log-level CLI flag) and
refactors applog into an intent-based facade with three tiers:

- Debug/Info/Warn/Error: file only
- Status: footer only (transient UI feedback)
- UserWarn/UserError: both file and footer

The footer ring buffer is preserved unchanged; the file sink is layered
behind an atomic.Pointer[*slog.Logger] so log calls stay lock-free.

Migrated all 11 spotify call sites: failures saving credentials and the
auth-callback server error to UserError, reconnect/rate-limit warnings
to UserWarn, 're-authenticated successfully' to Info+Status.

Plugin-side logging and log rotation deferred to follow-ups.

* docs(site): add diagnostic logging feature card

Keeps site/index.html in sync with docs/configuration.md after the
log_level config key was added in abfdc37.

* Address CodeRabbit review

- config: silently fall back to default for invalid log_level in TOML,
  matching the loader's behavior for other keys (volume, repeat, etc.)
- spotify: extract duplicate re-auth message literal into a const
- main: return applied level from initLogging so the startup log records
  the level that's actually in effect, not the raw config string

* Drop Enabled gate from UserWarn/UserError

The footer needs the formatted string regardless of file-log level, so
the gate was paying for two fmt.Sprintf sites and a branch in exchange
for skipping a sub-nanosecond slog dispatch. Diagnostic-only methods
(Debug/Info/Warn/Error/logf) keep the gate where it actually avoids the
Sprintf cost.

* applog: use t.Cleanup for test logger close

Resolves three errcheck violations from `defer closeFn()` by switching
to `t.Cleanup(func() { _ = closeFn() })`. The explicit underscore
documents the discard intent and t.Cleanup is the idiomatic place to
register test resource teardown.

Author: bjarneo

applog/applog.go

@@ -1,46 +1,179 @@
-// Package applog provides a thread-safe in-app log buffer for messages that
-// would otherwise be written to stderr (which corrupts the TUI).
+// Package applog provides logging for cliamp.
+//
+// Two sinks are layered behind one API:
+//
+//   - A file sink, written through log/slog, for diagnostic logs the user
+//     reads after the fact (~/.config/cliamp/cliamp.log).
+//   - An in-memory ring buffer drained by the TUI footer for short-lived,
+//     user-facing messages. The buffer exists because writing to stderr
+//     would corrupt the TUI.
+//
+// Callers pick by intent, not sink:
+//
+//   - Debug/Info/Warn/Error    write only to the file.
+//   - Status                   writes only to the footer (transient UI
+//     feedback that wouldn't help post-mortem debugging).
+//   - UserWarn/UserError       write to both.
+//
+// Init must be called once at startup. Calls before Init are silently
+// dropped on the file side; the footer buffer always works.
 package applog
 
 import (
+	"context"
 	"fmt"
+	"io"
+	"log/slog"
+	"os"
+	"path/filepath"
+	"strings"
 	"sync"
+	"sync/atomic"
 	"time"
 )
 
-// Entry is a single log message with a timestamp.
+// Entry is a single footer message with a timestamp.
 type Entry struct {
 	Text string
 	At   time.Time
 }
 
+// Level is an alias for slog.Level so callers don't need a second import.
+type Level = slog.Level
+
+const (
+	LevelDebug = slog.LevelDebug
+	LevelInfo  = slog.LevelInfo
+	LevelWarn  = slog.LevelWarn
+	LevelError = slog.LevelError
+)
+
 const maxEntries = 4
 
 var (
-	mu      sync.Mutex
-	entries []Entry
+	logger atomic.Pointer[slog.Logger]
+
+	mu          sync.Mutex
+	entries     []Entry
+	currentFile io.Closer
 )
 
-// Printf writes a formatted log message to the buffer.
-func Printf(format string, args ...any) {
-	msg := fmt.Sprintf(format, args...)
-	mu.Lock()
-	entries = append(entries, Entry{Text: msg, At: time.Now()})
-	if len(entries) > maxEntries {
-		entries = entries[len(entries)-maxEntries:]
+func init() {
+	logger.Store(slog.New(slog.NewTextHandler(io.Discard, nil)))
+}
+
+// Init opens path for append, installs a slog text handler at the given
+// level, and returns a close func. Calling Init twice closes the previous
+// file before swapping handlers.
+func Init(path string, level Level) (func() error, error) {
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		return nil, fmt.Errorf("create log dir: %w", err)
 	}
+	f, err := os.OpenFile(path, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o644)
+	if err != nil {
+		return nil, fmt.Errorf("open log file: %w", err)
+	}
+
+	h := slog.NewTextHandler(f, &slog.HandlerOptions{Level: level})
+	logger.Store(slog.New(h))
+
+	mu.Lock()
+	prev := currentFile
+	currentFile = f
 	mu.Unlock()
+	if prev != nil {
+		_ = prev.Close()
+	}
+
+	return func() error {
+		mu.Lock()
+		defer mu.Unlock()
+		if currentFile == nil {
+			return nil
+		}
+		err := currentFile.Close()
+		currentFile = nil
+		logger.Store(slog.New(slog.NewTextHandler(io.Discard, nil)))
+		return err
+	}, nil
+}
+
+// ParseLevel maps a string to a Level. Empty input maps to LevelInfo.
+// "warning" is accepted as an alias for "warn".
+func ParseLevel(s string) (Level, error) {
+	s = strings.TrimSpace(s)
+	if s == "" {
+		return LevelInfo, nil
+	}
+	if strings.EqualFold(s, "warning") {
+		return LevelWarn, nil
+	}
+	var lvl Level
+	if err := lvl.UnmarshalText([]byte(strings.ToUpper(s))); err != nil {
+		return LevelInfo, fmt.Errorf("invalid log level %q (want debug|info|warn|error)", s)
+	}
+	return lvl, nil
 }
 
-// Drain returns all buffered entries and clears the buffer.
+// Debug, Info, Warn, Error log only to the file. Format follows fmt.Sprintf.
+// The level guard avoids paying the Sprintf cost when the level is filtered out.
+func Debug(format string, args ...any) { logf(slog.LevelDebug, format, args...) }
+func Info(format string, args ...any)  { logf(slog.LevelInfo, format, args...) }
+func Warn(format string, args ...any)  { logf(slog.LevelWarn, format, args...) }
+func Error(format string, args ...any) { logf(slog.LevelError, format, args...) }
+
+// Status pushes a message into the footer buffer without writing to the
+// log file. Use for ephemeral, user-facing notifications that wouldn't help
+// post-mortem debugging.
+func Status(format string, args ...any) {
+	pushFooter(fmt.Sprintf(format, args...))
+}
+
+// UserWarn logs at warn level and pushes the same message into the footer.
+// The Sprintf cost is paid unconditionally because the footer needs the
+// formatted string, so no Enabled gate here.
+func UserWarn(format string, args ...any) {
+	msg := fmt.Sprintf(format, args...)
+	logger.Load().Warn(msg)
+	pushFooter(msg)
+}
+
+// UserError logs at error level and pushes the same message into the footer.
+func UserError(format string, args ...any) {
+	msg := fmt.Sprintf(format, args...)
+	logger.Load().Error(msg)
+	pushFooter(msg)
+}
+
+// Drain returns and clears all buffered footer entries.
 func Drain() []Entry {
 	mu.Lock()
+	defer mu.Unlock()
 	if len(entries) == 0 {
-		mu.Unlock()
 		return nil
 	}
 	out := entries
 	entries = nil
-	mu.Unlock()
 	return out
 }
+
+func logf(level slog.Level, format string, args ...any) {
+	lg := logger.Load()
+	if !lg.Enabled(context.Background(), level) {
+		return
+	}
+	lg.Log(context.Background(), level, fmt.Sprintf(format, args...))
+}
+
+func pushFooter(msg string) {
+	msg = strings.TrimRight(msg, "\n")
+	if msg == "" {
+		return
+	}
+	mu.Lock()
+	entries = append(entries, Entry{Text: msg, At: time.Now()})
+	if len(entries) > maxEntries {
+		entries = entries[len(entries)-maxEntries:]
+	}
+	mu.Unlock()
+}