Auto-detect Docker Desktop socket on Linux

[samuv]

Summary

• On Linux, when Docker Desktop is the only Docker installation (no system Docker Engine on /var/run/docker.sock), thv fails to start with no container runtime available, even though docker / docker ps work fine. Docker Desktop on Linux runs Engine inside a VM and exposes its socket at ~/.docker/desktop/docker.sock and registers a desktop-linux Docker CLI context pointing there. findDockerSocket only probed /var/run/docker.sock plus macOS-specific paths (Docker Desktop on macOS, Rancher Desktop, OrbStack), so the Linux Docker Desktop socket was never discovered. The Docker CLI works because it honors ~/.docker/config.json / ~/.docker/contexts/meta; ToolHive's Go discovery does not consult contexts, it stats a fixed list.
• Add the Linux Docker Desktop socket path to the auto-detection list so users with only Docker Desktop installed do not have to set TOOLHIVE_DOCKER_SOCKET manually.
• Three independent commits — production fix, unit tests, doc update — so each can be reviewed / reverted in isolation.

Fixes #5120

Type of change

• Bug fix

Test plan

• Unit tests (go test ./pkg/container/docker/sdk/... ./pkg/container/...)
• Linting (task lint-fix — 0 issues)
• Three new test cases in pkg/container/docker/sdk/client_unix_test.go:
  • TestFindDockerSocket_DockerDesktopOnLinux — hermetic test that creates a fake ~/.docker/desktop/docker.sock and asserts findDockerSocket returns it.
  • TestFindPlatformContainerSocket_DockerEnvOverrideWins — TOOLHIVE_DOCKER_SOCKET takes precedence over filesystem discovery.
  • TestFindPlatformContainerSocket_NotFound — ErrRuntimeNotFound is still returned when no socket is reachable.
• Manual testing on a Linux host with only Docker Desktop installed — pending; happy to defer to a reviewer with that setup, or I can spin up a Linux VM with Docker Desktop and confirm thv version / thv list work without the env override.

Changes

File	Change
pkg/container/docker/sdk/factory.go	Add DockerDesktopLinuxSocketPath constant for ~/.docker/desktop/docker.sock.
pkg/container/docker/sdk/client_unix.go	Probe Docker Desktop on Linux path in findDockerSocket; wrap the system socket path in unexported systemDockerSocketPath so tests can redirect it.
pkg/container/docker/sdk/client_unix_test.go	New file — three table-style cases for socket discovery (Linux Docker Desktop, env override, not-found).
docs/arch/01-deployment-modes.md	Add the new path to the documented Docker discovery order.

Does this introduce a user-facing change?

Yes — Linux users running only Docker Desktop now get working thv runtime auto-detection with no extra configuration. Hosts that already have /var/run/docker.sock (system Docker Engine) see no change; the system socket is still probed first and wins.

Implementation plan

Approved implementation plan

1. Add DockerDesktopLinuxSocketPath = ".docker/desktop/docker.sock" next to the other socket-path constants in pkg/container/docker/sdk/factory.go.
2. Extend findDockerSocket in pkg/container/docker/sdk/client_unix.go to probe $HOME/.docker/desktop/docker.sock, ordered after the macOS Docker Desktop check and before the Rancher / OrbStack fallbacks. Keep /var/run/docker.sock first so a system Docker Engine still wins.
3. Wrap the system socket path in an unexported systemDockerSocketPath package variable defaulted to DockerSocketPath so tests can redirect the system probe to a sandbox path without affecting production.
4. Add unit tests in pkg/container/docker/sdk/client_unix_test.go covering: discovery of the new Linux Docker Desktop socket, env override (TOOLHIVE_DOCKER_SOCKET) precedence, and ErrRuntimeNotFound when nothing is reachable.
5. Update docs/arch/01-deployment-modes.md so the documented discovery order matches the code.

Out of scope: parsing ~/.docker/config.json / ~/.docker/contexts/meta to honor arbitrary Docker contexts. That generalizes beyond the well-known Docker Desktop path but is heavier; leaving it as a follow-up if a custom-context case shows up.

Special notes for reviewers

• The new systemDockerSocketPath variable is unexported and exists purely as a test seam — its production value is DockerSocketPath and never changes at runtime.
• Until this lands, affected users can work around the issue with:

  export TOOLHIVE_DOCKER_SOCKET="$HOME/.docker/desktop/docker.sock"

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 67.15%. Comparing base (4c23ade) to head (6ad9dfc).
⚠️ Report is 10 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5122      +/-   ##
==========================================
+ Coverage   67.12%   67.15%   +0.03%     
==========================================
  Files         597      597              
  Lines       60170    60177       +7     
==========================================
+ Hits        40390    40414      +24     
+ Misses      16706    16686      -20     
- Partials     3074     3077       +3     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.