[Maui.Client] API Design Improvements — Multi-Model Review Findings

[rmarinho]

Summary

After a multi-model AI review of the Microsoft.Maui.Client CLI tool (PR #34498), three independent models (Gemini 3 Pro, GPT-5.1, Claude Sonnet 4.5) were asked to review the public API surface and suggest improvements. This issue captures the consensus findings and highest-value ideas for future iterations.

Consensus: All 3 Models Independently Identified

1. Command Hierarchy Inconsistencies

Current	Proposed	Reason
maui apple install <runtime-id>	maui apple runtime install <id>	Matches android sdk install pattern
maui android install + maui android sdk install	Remove android install, keep sdk install	Redundant entry points confuse users
No maui apple device list	Add maui apple device list	Physical iOS device listing missing (asymmetric with Android)
maui doctor [--fix]	maui doctor android, maui doctor apple, maui doctor jdk	Granular checks instead of all-or-nothing

2. IAndroidProvider is a God Interface

All models flagged that IAndroidProvider combines SDK, JDK, Emulator, and Device management into a single interface. This violates Interface Segregation and makes testing harder.

Suggestion: Split into IAndroidSdkManager, IAndroidEmulatorService, IJdkInstaller (or similar boundaries).

3. Missing Day Zero Experience

All models independently suggested a guided setup command:

maui setup [--platform android|apple|all] [--non-interactive] [--accept-licenses]

This would orchestrate: detect OS, install SDK, install JDK, accept licenses, create default emulator/simulator, run doctor to verify.

4. Missing Configuration Persistence

maui config set android.sdk.path ~/Android/sdk
maui config set jdk.path /usr/local/jdk-17
maui config get
maui config list

Central place for paths, preferred versions, default device IDs. Backed by JSON in user profile.

High-Value Ideas (2+ Models Agree)

Feature	Models	Description
apple runtime uninstall	GPT, Claude	Missing symmetry - can install but not uninstall
Workload integration	Gemini, GPT	maui workload status wrapping dotnet workload list filtered to MAUI
Project-aware checks	GPT, Claude	maui project inspect . - parse csproj, check TFMs vs installed tooling
JDK version switching	GPT, Claude	maui android jdk use 17 / jdk use 21 (like nvm/sdkman)
maui nuke/reset	Gemini, Claude	Clear caches, stop emulators, restart adb, clean bin/obj
Workspace config files	GPT, Claude	.maui/config.json checked into repo for team-shared settings

Best Unique Ideas Per Model

Gemini 3 Pro

• Interactive Spectre selection when args missing - Instead of erroring on missing args, show interactive picker
• Don't maintain local state DB - Always query source of truth (sdkmanager, simctl) to avoid state drift
• Log analysis: maui logs --app com.company.myapp --crash-only - filter logcat firehose to app PID + crashes

GPT-5.1

• JSON schema versioning: { schema: maui/v1, ... } for stable CLI output contracts
• Result<T> pattern instead of exceptions for structured error handling in scripting scenarios
• Rename Runtime to AppleRuntime to avoid conceptual collision with .NET runtimes
• Golden JSON output tests to guard CLI output contracts against breaking changes
• CancellationToken on all async provider methods - long installs/downloads need graceful CTRL+C

Claude Sonnet 4.5

• maui bootstrap --preset ci - CI-specific minimal, non-interactive setup
• maui wait-for-device <id> --timeout 5m - CI-friendly device readiness check
• Actionable error messages with recovery suggestions
• maui ci export --output github - Generate GitHub Actions / Azure Pipelines yaml snippets
• maui app install/launch <bundle-id> --device <id> - App lifecycle management

Architecture Suggestions

• Plugin system (IMauiPlugin) for community extensions (longer term)
• Structured logging with Microsoft.Extensions.Logging (replace current Trace.WriteLine)
• --format table|json|yaml and --quiet as global options on all list commands
• Progress bars (Spectre.Console) for long-running downloads/installs
• --dry-run / --what-if for heavyweight operations

Proposed Priority

Phase 1 (Pre-GA)

1. Fix command hierarchy (move apple install to apple runtime install, remove redundant android install)
2. Add maui setup guided experience
3. Add per-platform doctor android|apple|jdk
4. Add --quiet and --verbose global flags

Phase 2 (Post-GA)

5. Add maui config persistence
6. Add apple runtime uninstall
7. Split IAndroidProvider into smaller interfaces
8. Add project-aware checks (maui project inspect)

Phase 3 (Future)

9. Workspace config files (.maui/config.json)
10. CI integration helpers
11. Plugin system
12. App lifecycle management

---

Generated from multi-model review of PR #34498. Models used: Gemini 3 Pro Preview, GPT-5.1, Claude Sonnet 4.5.