v2.0.0 - Major CLI Architecture & Run Command Overhaul

Major Architecture Changes & Critical Fixes

Breaking Changes

• CLI-First Architecture - Complete restructuring where the CLI (xcodecontrol) is now the primary implementation, with the MCP server spawning CLI subprocesses for consistency
• Tool Name Standardization - CLI commands now use dash-separated names (open-project, health-check) instead of underscores for improved usability

Critical Run Command Fixes

• Eliminated stale build log detection - Fixed race condition where xcode_run would read previous build logs instead of current execution logs
• Resolved run command stalling - Fixed infinite hanging when apps launched successfully by implementing proper AppleScript completion handlers for run actions
• AppleScript monitoring overhaul - Replaced unreliable build log file monitoring with direct Xcode action status detection using completion handlers

Full CLI Feature Parity

• Complete tool coverage - All 24 MCP tools now available as CLI commands, up from 4 hardcoded tools
• Enhanced verbosity control - Added -v/--verbose and -q/--quiet flags with proper log level management
• Improved error handling - Special-cased health check exit codes to distinguish between degraded mode and critical failures
• JSON input/output support - Full compatibility with both command-line flags and JSON input formats

Technical Improvements

• Shared tool definitions - Single source of truth for tool schemas used by both CLI and MCP server to ensure consistency
• Robust CI/CD pipeline - Fixed all test failures including command name mapping, health check validation, and integration test expectations
• Documentation updates - Comprehensive README updates documenting dual CLI/MCP usage modes with correct command examples

Reliability Enhancements

• Race condition elimination - Proper timing of build log detection prevents reading stale data from previous runs
• Action-specific handling - Run actions now properly handle their unique "running" status behavior that differs from build/test actions
• Environment validation - Enhanced health checks with degraded mode support when optional dependencies are missing

Impact

This major release fundamentally changes the architecture to prioritize CLI usage while maintaining full MCP compatibility. The run command fixes resolve the most critical user-reported issues with build log detection and command stalling.

Breaking Change Notice: CLI command names now use dashes instead of underscores. Update any automation scripts accordingly.

Recommended for all users - especially those experiencing run command issues or requiring reliable CLI automation.

v1.8.0 - Test Execution & XCResult Parsing Fixes

Major Stability and Reliability Improvements

Critical Fixes

• Test execution hanging resolved - Eliminated infinite loops in AppleScript build monitoring that caused xcode_test to hang indefinitely when tests succeeded
• XCResult parsing failures fixed - Resolved false positive "corrupt XCResult" errors that prevented test result analysis
• Process handling improvements - Fixed Node.js child process event order issues that caused premature Promise rejections

Technical Improvements

• Modern xcresulttool API migration - Replaced deprecated legacy commands with current test-results API for better reliability and future-proofing
• Enhanced error handling - Improved Promise resolution logic and eliminated race conditions in XCResult parsing
• Simplified build monitoring - Replaced unreliable AppleScript polling with timeout-based approach for better consistency
• Updated data structures - Fixed TypeScript interfaces to match new xcresulttool output format

Reliability Enhancements

• All xcresult_* tools (browse, summary, activities, etc.) now function consistently
• xcode_test properly handles both build failure and success scenarios without hanging
• Eliminated false positive Xcode bug reports that occurred during normal operation
• Better debugging capabilities with enhanced logging

Impact

This release addresses the two most common stability issues reported by users: test execution hanging and XCResult parsing failures. These fixes ensure that test automation workflows complete successfully and provide accurate results.

Recommended for all users experiencing test execution issues or XCResult parsing errors.

v1.7.4 - Critical Crash Prevention

Critical Server Stability Fix

Emergency Crash Prevention

• Eliminated xcode_close_project crashes - Simplified close logic to prevent complex timeout scenarios that caused server termination
• JXA Process Safety - Added 30-second timeouts and proper cleanup to prevent hanging child processes
• Triple-Layer Error Handling - Wrapped close operations in multiple try-catch blocks to ensure no exceptions escape
• Simplified Dialog Handling - Removed complex dialog detection that could cause race conditions

Technical Implementation

• Streamlined closeProject from 160+ lines to 28 lines of robust, crash-proof code
• Added comprehensive process cleanup in JXAExecutor with timeout protection
• Enhanced error boundaries around all Xcode automation operations
• Guaranteed server survival even if Xcode operations fail catastrophically

Why This Release is Critical

The previous version still experienced "transport closed" errors after xcode_close_project operations, despite initial crash prevention attempts. This release addresses the root cause with a complete rewrite of the close project logic and bulletproof error handling.

This version should eliminate all unexpected server terminations during normal operation.

v1.7.3 - Server Stability & Test Execution Fixes

Server Stability & Reliability Improvements

Critical Bug Fixes

• Transport Closed Errors - Eliminated aggressive uncaught exception handler that was terminating MCP server connections
• Versioned Xcode Support - Fixed permission validation to work with non-standard Xcode installations (e.g., Xcode-16.4.0.app)
• Test Execution Hangs - Reduced xcode_test timeouts from hours to seconds, preventing infinite waits when tests don't run
• XCResult Staging Case Sensitivity - Fixed staging folder detection bug on case-sensitive filesystems

Enhanced Error Handling

• Comprehensive Logging - Added detailed error logging with stack traces for better debugging
• Graceful Degradation - Server now continues operating after exceptions instead of crashing
• Clear Error Messages - Added helpful guidance when tests fail to run due to missing test targets
• Alert Detection Improvements - Enhanced Xcode dialog handling with detailed button logging

Test Execution Reliability

• Smart Timeout Management - Build log detection: 10 minutes → 10 seconds, Test completion: 12 hours → 30 seconds
• No-Test Detection - Provides clear feedback when current scheme lacks test targets
• XCResult File Validation - Improved detection and handling of test result files
• Better Scheme Guidance - Suggests using test-specific schemes when tests don't execute

Technical Implementation

• Removed process.exit() calls from exception handlers to maintain server stability
• Dynamic Xcode path resolution using xcode-select with intelligent fallbacks
• Enhanced JXA automation with better error recovery and dialog handling
• Robust timeout management prevents indefinite hangs in test operations

This release significantly improves server reliability and eliminates the transport closure issues that could interrupt MCP sessions during Xcode operations.

v1.7.2

Technical Improvements

XCResult Analysis Enhancement

• Fixed xcresult file selection to correctly return latest test results
• Improved test timestamp accuracy for screenshot extraction
• Enhanced error handling in xcresult browser console output

Test Execution Reliability

• Increased test execution timeout to 12 hours for long-running test suites
• Fixed timeout logic to properly wait for test completion before staging timeout
• Improved test status tracking and completion detection

MCP Protocol Compliance

• Added proper MCP over SSE support with session management
• Fixed TypeScript errors in xcresult file selection logic
• Enhanced parameter validation across tool implementations

This patch release improves test result analysis accuracy and reliability for extended test execution scenarios while maintaining full backward compatibility.

v1.7.1 - XCResult Reliability & Error Handling

XCResult Reliability & Stability Improvements

Bug Fixes

• XCResult Corruption Prevention - Fixed race condition where XCResult files were read while Xcode was still writing them
• Staging Folder Detection - Now waits for XCResult staging folder to disappear before attempting to read results
• Transport Closed Errors - Eliminated crashes caused by unhandled promise rejections and hanging processes
• Complete Build Reporting - Fixed xcode_test to properly report both build errors AND warnings (was missing warnings)

Improvements

• Cleaner Output - Removed verbose repeated file paths from XCResult command examples
• Better Error Messages - Parameter validation now shows the actual required parameter name instead of generic messages
• Extended Timeouts - Increased staging detection timeout to 15 minutes for complex test suites
• Process Cleanup - Added proper cleanup handlers for child processes and timeouts

Technical Implementation

• Smart staging folder monitoring prevents file corruption
• Comprehensive error handling with graceful shutdowns
• Memory leak prevention for EventEmitter listeners
• Robust timeout management for long-running operations

This release significantly improves the reliability of test operations and eliminates the XCResult corruption issues that could cause transport failures.

v1.7.0 - Enhanced Project Management & Auto-Launch

🚀 Enhanced Project Management & Auto-Launch

New Features

• 🆕 xcode_close_project tool - Close projects with automatic dialog handling
• ⚡ Auto-launch Xcode - Automatically launches Xcode when not running using xcode-select -p
• 🔄 Enhanced project loading - Waits for projects to fully load before proceeding

Improvements

• 🛡️ Robust dialog handling - Automatically handles "Stop Tasks" and "Are you sure you want to close" dialogs
• ⏱️ Timeout protection - 5-second timeouts prevent MCP calls from hanging
• 🔧 Race condition fixes - No more "project still loading" errors when building immediately after opening
• 📂 Auto-open projects - Build commands automatically open projects when needed

Technical Enhancements

• Smart dialog detection using both description and subrole checks
• Comprehensive error handling with helpful recovery instructions
• Non-blocking operations with proper fallback mechanisms
• Integration with system Xcode configuration via xcode-select

This release provides a seamless, fully automated Xcode project management experience through MCP! 🎉

v1.6.2 - Automatic Build Conflict Resolution

Alert Handling

• Automatic Conflict Resolution: Automatically detects and handles alerts when starting builds/tests while another operation is in progress
• Multi-Modal Detection: Supports both traditional modal alert sheets and embedded window alerts
• Comprehensive Coverage: Handles 'replace existing build' dialogs, test conflict alerts, and similar interruption scenarios
• Non-Intrusive: Graceful fallback handling that doesn't interfere with normal operations when no alerts are present

Technical Implementation

• Multi-Level Detection: Searches for alerts in modal sheets, embedded UI elements, and system-level dialogs
• Smart Button Recognition: Identifies 'Replace', 'Stop', 'OK', and 'Yes' buttons automatically
• Descriptive Element Matching: Finds clickable elements with relevant descriptive text
• Robust Error Handling: Continues operation even if alert detection fails

This release eliminates the need for manual intervention when starting builds while other operations are active.

v1.6.1 - Extended Test Timeout

Timeout Fix

• Test Timeout: Increased test build timeout from 2 minutes to 10 minutes to accommodate slow Swift Package Manager dependency resolution
• Error Messages: Updated timeout error messages to reflect the new 10-minute limit

This patch release addresses timeout issues when Swift packages take longer than 2 minutes to resolve dependencies during test builds.

v1.6.0 - Enhanced XCResult Analysis and UI Hierarchy Tools

XCResult Analysis Improvements

• UI Hierarchy Tools: Added comprehensive XCResult UI hierarchy analysis with automatic screenshot extraction and timestamp-based attachment selection
• Screenshot Extraction: New xcresult_get_screenshot tool extracts PNG frames from UI test videos at specified timestamps
• Enhanced Test Analysis: Improved XCResult browsing tools with AI-readable UI hierarchy data and comprehensive test result formatting

Technical Enhancements

• Timestamp Handling: Fixed UI hierarchy timestamp extraction with proper relative time calculation for accurate screenshot timing
• Data Compression: Implemented slim UI hierarchy output with compact JSON formatting while removing redundant frame properties
• Parameter Clarity: Renamed tool parameters from generic 'path' to specific 'xcodeproj' for better clarity across all build tools
• Test Completion: Enhanced test completion detection and messaging with comprehensive XCResult tool integration

Reliability Improvements

• Timeout Handling: Increased xcode_test timeout values to accommodate Swift Package resolution delays
• Build Failure Detection: Fixed xcode_test hanging issues on build failures with proper completion tracking
• Health Check: Added version number reporting to health check tool for better diagnostics

Breaking Changes

• Tool parameters now use 'xcodeproj' instead of 'path' for consistency across the codebase