Read-only shared settings spine

[msgerbush]

Closes #148

Summary

Implements Phase 1 of the shared settings system: a read-only settings spine that becomes the single source of truth for playback and admin startup.

This adds the canonical persisted settings schema, sparse file loading from ~/.jukebox/settings.json, migration/version handling, effective settings resolution with precedence defaults < file < env < CLI, and read-only settings inspection through admin CLI/API surfaces.

What Changed

• added shared settings entities, repository, migration, and resolution logic under jukebox/settings/
• moved jukebox startup to consume resolved runtime config from the shared settings layer
• moved discstore startup to consume resolved admin runtime config from the shared settings layer
• added read-only admin settings inspection commands:
  • discstore settings show
  • discstore settings show --effective
• added read-only admin API endpoints:
  • GET /api/v1/settings
  • GET /api/v1/settings/effective
• added effective settings provenance reporting and derived path reporting
• documented validation boundaries for shared settings vs runtime-specific validation

CLI Behavior Change

• jukebox CLI parsing is now override-oriented instead of requiring a fully runnable config up front.
• Positional PLAYER READER args are still accepted, but they are now optional.
• --player and --reader can be provided independently, with final runtime values resolved from shared settings using defaults < file < env < CLI.
• Validation for “is this runnable?” now happens when building resolved runtime config, not during raw CLI parsing.

Architectural Notes

• CLI parsing now collects command intent and process-local overrides, but application startup resolves canonical runtime config through the shared settings layer.
• Validation is split across three boundaries:
  • persisted settings shape and migration
  • effective merged settings shape
  • runtime-specific invariants
• Runtime-only requirements stay out of shared effective settings resolution so admin/settings inspection can still work when jukebox-specific settings are incomplete.

Notes

• this phase is read-only only; it does not add settings mutation, reset flows, or settings editing UI

[Gudsfile]

I haven’t fully reviewed yet, but I tried it out and the result looks great!

A couple of one initial observations, feel free to handle later if planned):

• Using a wrong command triggers a Pydantic error instead of showing --help or prompting the user. For example:

  uv run jukebox
  Invalid effective settings after CLI overrides: 1 validation error for ResolvedJukeboxRuntimeConfig
    Value error, Sonos player requires an active host ...

  edit: this only happens if no config file exists yet, so it may be resolved once file writing is implemented.
• I also initially misunderstood that we shouldn’t use the full output of --effective, but that's only temporary, haha.

  uv run discstore -- settings show --effective | jq '.settings' | pbcopy
  pbpaste > ~/.jukebox/settings.json
  uv run jukebox
  

[msgerbush]

• Using a wrong command triggers a Pydantic error instead of showing --help or prompting the user. For example:

  uv run jukebox
  Invalid effective settings after CLI overrides: 1 validation error for ResolvedJukeboxRuntimeConfig
    Value error, Sonos player requires an active host ...

Hmmm, this one is unexpected. Invalid effective settings after CLI overrides should only show up when cli_overrides is non empty. I would've expected this if it ran with something like uv run jukebox sonos or uv run jukebox --player sonos. Is this still happening on this branch?

[msgerbush]

• I also initially misunderstood that we shouldn’t use the full output of --effective, but that's only temporary, haha.

  uv run discstore -- settings show --effective | jq '.settings' | pbcopy
  pbpaste > ~/.jukebox/settings.json
  uv run jukebox
  

ah, I want the CLI to be intuitive, so if you think it's not clear I'm happy to change it!

the settings.json file itself is sparse (and not required), so it won't include default values--it's just the minimum settings needed to reproduce your environment. if you're just looking to save or export your settings file so you can use it in another environment, you can run uv run discstore settings show > ~/.jukebox/settings.json.

Without --effective it won't dump the full list of settings, just the ones where you override the defaults. --effective is the full list of everything, which is more as a diagnostic or if you really want to pin all the values exactly for some reason.

[Gudsfile]

• Using a wrong command triggers a Pydantic error instead of showing --help or prompting the user. For example:

  uv run jukebox
  Invalid effective settings after CLI overrides: 1 validation error for ResolvedJukeboxRuntimeConfig
    Value error, Sonos player requires an active host ...

Hmmm, this one is unexpected. Invalid effective settings after CLI overrides should only show up when cli_overrides is non empty. I would've expected this if it ran with something like uv run jukebox sonos or uv run jukebox --player sonos. Is this still happening on this branch?

You're right, sorry about that, I gave you the wrong information about my test. Anyway, it doesn't happen anymore with the latest version of the branch, regardless of the command (rm ~/.jukebox/settings.json, uv run jukebox, uv run jukebox --player sonos) 🚀

[Gudsfile]

There's a lot to it! But the tests really help me understand it, thanks for that.
I’ve just got a few comments, which are actually more like questions. I might have some further points later, but I’m happy with the direction subject is taking for now.

OK to merge it as it is.

[Gudsfile]

Phase 1 🚀