Add CLI validation for Desktop app alignment

[samuv]

Summary

Add CLI validation to detect when ToolHive Desktop manages CLI installation, preventing version conflicts that cause API incompatibilities.

When the Desktop app installs the CLI, it creates a marker file at ~/.toolhive/.cli-source. This PR adds validation that runs before every CLI command to detect conflicts between standalone CLI and Desktop-managed installations.

Validation Flow

flowchart TD
    A[CLI Command Invoked] --> B[Read ~/.toolhive/.cli-source]
    B -->|Not Found| C[Proceed Normally]
    B -->|Found| D[Check symlink_target exists]
    D -->|Missing| C
    D -->|Exists| E{Current CLI matches target?}
    E -->|Yes| C
    E -->|No| F[Hard Stop with Error]

Loading

Key Changes

• New pkg/desktop/ package - Types, marker file reading, and validation logic
• Root command integration - PersistentPreRunE hook validates desktop alignment before every command
• Skip override - TOOLHIVE_SKIP_DESKTOP_CHECK=1 bypasses validation for debugging

Scenarios Handled

Scenario	Behavior
No marker file	Proceed normally
Marker exists, target binary missing	Proceed (Desktop uninstalled, stale marker)
Marker exists, current CLI matches target	Proceed (we are the Desktop CLI)
Marker exists, current CLI differs	Hard stop with actionable error

Related

• Related to: toolhive-studio#1512
• RFC: THV-0020 - Desktop CLI Version Alignment

Large PR Justification

• e2e tests and unit tests
• new module

[github-actions]

Large PR Detected

This PR exceeds 1000 lines of changes and requires justification before it can be reviewed.

How to unblock this PR:

Add a section to your PR description with the following format:

## Large PR Justification

[Explain why this PR must be large, such as:]
- Generated code that cannot be split
- Large refactoring that must be atomic
- Multiple related changes that would break if separated
- Migration or data transformation

Alternative:

Consider splitting this PR into smaller, focused changes (< 1000 lines each) for easier review and reduced risk.

See our Contributing Guidelines for more details.

---

This review will be automatically dismissed once you add the justification section.

[codecov]

Codecov Report

❌ Patch coverage is 73.80952% with 33 lines in your changes missing coverage. Please review.
✅ Project coverage is 65.53%. Comparing base (fa56a01) to head (724b170).
⚠️ Report is 3 commits behind head on main.

Files with missing lines	Patch %	Lines
pkg/desktop/validation.go	71.73%	18 Missing and 8 partials ⚠️
pkg/desktop/marker.go	79.41%	4 Missing and 3 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3535      +/-   ##
==========================================
- Coverage   65.54%   65.53%   -0.01%     
==========================================
  Files         404      406       +2     
  Lines       39873    39999     +126     
==========================================
+ Hits        26133    26212      +79     
- Misses      11715    11756      +41     
- Partials     2025     2031       +6     

☔ 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.

Large PR justification has been provided. Thank you!

[github-actions]

✅ Large PR justification has been provided. The size review has been dismissed and this PR can now proceed with normal review.

[samuv]

@dmjb I think I’ve addressed your feedback on keeping anything that doesn’t need to be shared private