Merge pull request #2 from wasabeef/feat-adk-installer

Author: wasabeef

CLAUDE.md

@@ -52,6 +52,7 @@ The `DeviceManager` trait (in `managers/common.rs`) provides a unified interface
 - Device type selection (iPhone, iPad models)
 - Runtime version selection
 - Basic device operations with status monitoring
+- Automatic Simulator.app lifecycle management (opens on start, quits when last device stops)
 
 ### User Interface
 - **Three-panel layout**: Android devices (30%) | iOS devices (30%) | Device details (40%)
@@ -153,6 +154,12 @@ cargo test startup_performance_test -- --nocapture
 - ✅ Device details with MB units and full paths
 - ✅ Comprehensive test suite
 - ✅ Operation status tracking and notifications
+- ✅ API level management with real-time installation
+- ✅ Device creation cache system (5-minute expiration)
+- ✅ Modular constants architecture (`src/constants/`)
+- ✅ Form validation framework (`src/utils/validation.rs`)
+- ✅ Enhanced command execution utilities with retry and error ignoring
+- ✅ iOS Simulator.app automatic lifecycle management
 
 ### Known Issues & Limitations
 - **Android state detection**: Occasional inaccuracy in AVD name to emulator serial mapping (improved but not perfect)
@@ -189,6 +196,18 @@ cargo test startup_performance_test -- --nocapture
 - `src/models/error.rs` - Error types and user-friendly formatting
 - `src/models/platform.rs` - Platform enums and device configurations
 
+### Constants & Utilities
+- `src/constants/` - Modular constants system
+  - `commands.rs` - CLI tool names and arguments
+  - `defaults.rs` - Default values and configurations
+  - `env_vars.rs` - Environment variable names
+  - `files.rs` - File paths and extensions
+  - `messages.rs` - User-facing strings
+  - `patterns.rs` - Regular expressions
+  - `performance.rs` - Performance tuning parameters
+- `src/utils/validation.rs` - Form field validation framework
+- `src/utils/command.rs` - Enhanced command execution with retry and error handling
+
 ## Code Conventions
 
 ### Error Handling

README.md

@@ -15,6 +15,7 @@ https://github.com/user-attachments/assets/0ff745ce-7329-4af8-b529-6c5b30d3c48e
   - Support for Phone, Tablet, TV, Wear OS, Automotive, Desktop device types
   - Advanced configuration: RAM (512MB-8GB), Storage (1GB-64GB)
   - Automatic placeholder naming (e.g., "Pixel 9 Pro Fold API 36")
+  - Real-time system image installation with progress tracking
 - 🍎 **iOS Simulator Management** (macOS only): Manage simulators via `xcrun simctl`
   - Device type selection (iPhone, iPad models)
   - Runtime version selection with dynamic detection
@@ -28,6 +29,7 @@ https://github.com/user-attachments/assets/0ff745ce-7329-4af8-b529-6c5b30d3c48e
 - 🔍 **Comprehensive Details**: Device specifications, status, RAM/Storage in MB, full paths
 - 🧠 **Smart Caching**: Platform-aware cache invalidation and background loading
 - 📝 **Robust Testing**: 15 test files with 31+ test functions ensuring reliability
+- 📦 **API Level Management**: Install/uninstall system images directly from TUI
 
 ## Installation
 
@@ -72,6 +74,7 @@ emu --debug
 | `j`/`k` | Navigate devices (vim-style) |
 | `Enter` | Start/Stop device |
 | `c` | Create new device |
+| `i` | Manage API levels (Android) |
 | `d` | Delete device |
 | `w` | Wipe device |
 | `r` | Refresh |

docs/ARCHITECTURE.md

@@ -84,6 +84,10 @@ pub struct AppState {
     pub active_panel: Panel,
     pub selected_android: usize,
     pub selected_ios: usize,
+    pub mode: Mode,
+    
+    // API Level Management (New in v2.0)
+    pub api_level_management: Option<ApiLevelManagementState>,
 
     // Background operations
     pub is_loading: bool,
@@ -96,6 +100,11 @@ pub struct AppState {
     // Logging and notifications
     pub device_logs: VecDeque<LogEntry>,
     pub notifications: VecDeque<Notification>,
+    
+    // Dialogs
+    pub create_device_form: CreateDeviceForm,
+    pub confirm_delete_dialog: Option<ConfirmDeleteDialog>,
+    pub confirm_wipe_dialog: Option<ConfirmWipeDialog>,
 }
 ```
 
@@ -179,7 +188,27 @@ impl DeviceManager for IosManager {
 - Easy testing with mock implementations
 - Clear separation of platform-specific logic
 
-### 2. Async State Management
+### 2. API Level Management System (New)
+
+**Purpose**: Dynamic system image management for Android devices.
+
+```rust
+pub struct ApiLevelManagementState {
+    pub api_levels: Vec<ApiLevel>,
+    pub selected_index: usize,
+    pub is_loading: bool,
+    pub install_progress: Option<InstallProgress>,
+    pub scroll_offset: usize,
+}
+```
+
+**Features**:
+- Real-time installation progress tracking
+- Scrollable UI with keyboard navigation
+- Automatic cache invalidation on changes
+- Background installation with progress callbacks
+
+### 3. Async State Management
 
 **Purpose**: Provide thread-safe state access with non-blocking operations.
 
@@ -312,7 +341,7 @@ App::new() → tokio::spawn() → list_devices() → state.devices = ... → ren
 1. **Immediate UI Rendering**: Show interface within ~50ms
 2. **Background Data Loading**: Load device lists asynchronously
 3. **Progressive Enhancement**: Add features as data becomes available
-4. **Cache Utilization**: Use cached data when available
+4. **Cache Preloading**: Preload device types and API levels at startup
 5. **Target Performance**: Startup time < 150ms (typical: ~104ms)
 
 ### Runtime Optimization
@@ -466,4 +495,44 @@ async fn test_startup_performance() {
 - **predicates**: Complex assertion conditions
 - **Custom Assertions**: Domain-specific test helpers
 
+## New Features in v2.0
+
+### API Level Management
+- **Dynamic System Image Discovery**: Real-time detection of available system images
+- **Installation Progress Tracking**: Live progress updates during installation
+- **Smart Cache Invalidation**: Automatic cache refresh on system image changes
+- **Architecture Detection**: Automatic selection of optimal architecture (x86_64/arm64)
+
+### Enhanced Caching System
+- **Device Creation Cache**: Pre-loaded device types and API levels
+- **Background Refresh**: Automatic cache updates without blocking UI
+- **Context-Aware Invalidation**: Cache cleared on relevant operations
+
+### Improved User Experience
+- **Scrollable Dialogs**: Better handling of long lists
+- **Loading Indicators**: Clear feedback during async operations
+- **Keyboard Navigation**: Circular navigation in device lists
+- **Real-time Status Updates**: Live device status monitoring
+
+### iOS Simulator Integration
+- **Automatic App Lifecycle**: Simulator.app opens automatically when starting devices
+- **Smart Cleanup**: Simulator.app quits automatically when last device stops
+- **Graceful Shutdown**: Uses AppleScript for clean app termination with fallback
+- **Dock Management**: Prevents Simulator.app icon from lingering in Dock
+
+## Constants Architecture
+
+The application uses a modular constants system (`constants/`):
+
+```
+constants/
+├── commands.rs     # CLI tool names and arguments
+├── defaults.rs     # Default values and configurations
+├── env_vars.rs     # Environment variable names
+├── files.rs        # File paths and extensions
+├── messages.rs     # User-facing strings and messages
+├── patterns.rs     # Regular expressions for parsing
+└── performance.rs  # Performance tuning parameters
+```
+
 This architecture provides a solid foundation for building a responsive, maintainable, and cross-platform terminal application while ensuring reliability through comprehensive testing.

docs/DEVELOPMENT.md

@@ -135,7 +135,15 @@ src/
 │   ├── command.rs      # Command execution
 │   ├── logger.rs       # Logging utilities
 │   └── mod.rs          # Module exports
-├── constants.rs        # Application constants
+├── constants/          # Modular constants system
+│   ├── mod.rs         # Module exports
+│   ├── commands.rs    # CLI tool names and arguments
+│   ├── defaults.rs    # Default values and configurations
+│   ├── env_vars.rs    # Environment variable names
+│   ├── files.rs       # File paths and extensions
+│   ├── messages.rs    # User-facing strings
+│   ├── patterns.rs    # Regular expressions
+│   └── performance.rs # Performance tuning parameters
 ├── lib.rs             # Library root
 └── main.rs            # Application entry point
 ```
@@ -653,6 +661,128 @@ cargo publish
 2. **Monitor issues**: Watch for bug reports
 3. **Plan next release**: Update development roadmap
 
+## Constants Architecture
+
+### Overview
+The application uses a modular constants system to eliminate hardcoded strings and improve maintainability. Constants are organized by category in the `src/constants/` directory.
+
+### Module Structure
+
+```rust
+// src/constants/mod.rs - Public API
+pub mod commands;
+pub mod defaults;
+pub mod env_vars;
+pub mod files;
+pub mod messages;
+pub mod patterns;
+pub mod performance;
+
+// Usage example
+use crate::constants::{
+    commands::ANDROID_COMMANDS,
+    defaults::DEFAULT_RAM_SIZE,
+    messages::MSG_DEVICE_CREATED,
+};
+```
+
+### Categories
+
+#### Commands (`commands.rs`)
+- CLI tool names and paths
+- Command arguments
+- Platform-specific commands
+
+```rust
+pub const ADB: &str = "adb";
+pub const EMULATOR: &str = "emulator";
+pub const AVDMANAGER: &str = "avdmanager";
+```
+
+#### Defaults (`defaults.rs`)
+- Default configuration values
+- UI dimensions
+- Resource limits
+
+```rust
+pub const DEFAULT_RAM_SIZE: u32 = 2048; // MB
+pub const DEFAULT_STORAGE_SIZE: u32 = 8192; // MB
+pub const MAX_LOG_ENTRIES: usize = 1000;
+```
+
+#### Environment Variables (`env_vars.rs`)
+- System environment variable names
+- Configuration paths
+
+```rust
+pub const ANDROID_HOME: &str = "ANDROID_HOME";
+pub const RUST_LOG: &str = "RUST_LOG";
+```
+
+#### Files (`files.rs`)
+- File paths and extensions
+- Configuration file names
+
+```rust
+pub const AVD_CONFIG_FILE: &str = "config.ini";
+pub const HARDWARE_QEMU_INI: &str = "hardware-qemu.ini";
+```
+
+#### Messages (`messages.rs`)
+- User-facing strings
+- Error messages
+- Status notifications
+
+```rust
+pub const MSG_DEVICE_CREATED: &str = "Device created successfully";
+pub const MSG_LOADING_DEVICES: &str = "Loading devices...";
+```
+
+#### Patterns (`patterns.rs`)
+- Regular expressions
+- Parsing patterns
+
+```rust
+pub const DEVICE_NAME_PATTERN: &str = r"^[a-zA-Z0-9_.-]+$";
+pub const API_LEVEL_PATTERN: &str = r"API (\d+)";
+```
+
+#### Performance (`performance.rs`)
+- Timing constants
+- Debounce delays
+- Cache durations
+
+```rust
+pub const STARTUP_MAX_TIME_MS: u64 = 150;
+pub const UI_DEBOUNCE_MS: u64 = 50;
+pub const CACHE_EXPIRY_SECS: u64 = 300; // 5 minutes
+```
+
+### Best Practices
+
+1. **Naming Convention**: Use SCREAMING_SNAKE_CASE for constants
+2. **Documentation**: Add doc comments explaining usage
+3. **Organization**: Group related constants together
+4. **Type Safety**: Use appropriate types (not just `&str`)
+5. **Visibility**: Only export what's needed
+
+### Adding New Constants
+
+1. Determine the appropriate module based on category
+2. Add the constant with documentation
+3. Update module exports if needed
+4. Replace hardcoded values throughout codebase
+
+Example:
+```rust
+// In messages.rs
+/// Message shown when device deletion is confirmed
+pub const MSG_DEVICE_DELETED: &str = "Device deleted successfully";
+
+// Usage
+state.add_notification(MSG_DEVICE_DELETED, NotificationType::Success);
+```
+
 ## Best Practices Summary
 
 ### Code Quality