@leejungkiin/awkit 1.7.0 → 1.7.4

package/skills/ios-simulator-skill/scripts/screen_mapper.py

@@ -0,0 +1,296 @@
+#!/usr/bin/env python3
+"""
+iOS Screen Mapper - Current Screen Analyzer
+
+Maps the current screen's UI elements for navigation decisions.
+Provides token-efficient summaries of available interactions.
+
+This script analyzes the iOS simulator screen using IDB's accessibility tree
+and provides a compact, actionable summary of what's currently visible and
+interactive on the screen. Perfect for AI agents making navigation decisions.
+
+Key Features:
+- Token-efficient output (5-7 lines by default)
+- Identifies buttons, text fields, navigation elements
+- Counts interactive and focusable elements
+- Progressive detail with --verbose flag
+- Navigation hints with --hints flag
+
+Usage Examples:
+    # Quick summary (default)
+    python scripts/screen_mapper.py --udid <device-id>
+
+    # Detailed element breakdown
+    python scripts/screen_mapper.py --udid <device-id> --verbose
+
+    # Include navigation suggestions
+    python scripts/screen_mapper.py --udid <device-id> --hints
+
+    # Full JSON output for parsing
+    python scripts/screen_mapper.py --udid <device-id> --json
+
+Output Format (default):
+    Screen: LoginViewController (45 elements, 7 interactive)
+    Buttons: "Login", "Cancel", "Forgot Password"
+    TextFields: 2 (0 filled)
+    Navigation: NavBar: "Sign In"
+    Focusable: 7 elements
+
+Technical Details:
+- Uses IDB's accessibility tree via `idb ui describe-all --json --nested`
+- Parses IDB's array format: [{ root element with children }]
+- Identifies element types: Button, TextField, NavigationBar, TabBar, etc.
+- Extracts labels from AXLabel, AXValue, and AXUniqueId fields
+"""
+
+import argparse
+import json
+import subprocess
+import sys
+from collections import defaultdict
+
+from common import get_accessibility_tree, resolve_udid
+from common.env_config import env_int
+
+BUTTONS_PREVIEW = env_int("IOS_SIM_SCREEN_BUTTONS_PREVIEW", 15)
+SECTION_ITEMS_PREVIEW = env_int("IOS_SIM_SCREEN_SECTION_ITEMS", 10)
+
+
+class ScreenMapper:
+    """
+    Analyzes current screen for navigation decisions.
+
+    This class fetches the iOS accessibility tree from IDB and analyzes it
+    to provide actionable summaries for navigation. It categorizes elements
+    by type, counts interactive elements, and identifies key UI patterns.
+
+    Attributes:
+        udid (Optional[str]): Device UDID to target, or None for booted device
+        INTERACTIVE_TYPES (Set[str]): Element types that users can interact with
+
+    Design Philosophy:
+        - Token efficiency: Provide minimal but complete information
+        - Progressive disclosure: Summary by default, details on request
+        - Navigation-focused: Highlight elements relevant for automation
+    """
+
+    # Element types we care about for navigation
+    # These are the accessibility element types that indicate user interaction points
+    INTERACTIVE_TYPES = {
+        "Button",
+        "Link",
+        "TextField",
+        "SecureTextField",
+        "Cell",
+        "Switch",
+        "Slider",
+        "Stepper",
+        "SegmentedControl",
+        "TabBar",
+        "NavigationBar",
+        "Toolbar",
+    }
+
+    def __init__(self, udid: str | None = None):
+        """
+        Initialize screen mapper.
+
+        Args:
+            udid: Optional device UDID. If None, uses booted simulator.
+
+        Example:
+            mapper = ScreenMapper(udid="656DC652-1C9F-4AB2-AD4F-F38E65976BDA")
+            mapper = ScreenMapper()  # Uses booted device
+        """
+        self.udid = udid
+
+    def get_accessibility_tree(self) -> dict:
+        """
+        Fetch accessibility tree from iOS simulator via IDB.
+
+        Delegates to shared utility for consistent tree fetching across all scripts.
+        """
+        return get_accessibility_tree(self.udid, nested=True)
+
+    def analyze_tree(self, node: dict, depth: int = 0) -> dict:
+        """Analyze accessibility tree for navigation info."""
+        analysis = {
+            "elements_by_type": defaultdict(list),
+            "total_elements": 0,
+            "interactive_elements": 0,
+            "text_fields": [],
+            "buttons": [],
+            "navigation": {},
+            "screen_name": None,
+            "focusable": 0,
+        }
+
+        self._analyze_recursive(node, analysis, depth)
+
+        # Post-process for clean output
+        analysis["elements_by_type"] = dict(analysis["elements_by_type"])
+
+        return analysis
+
+    def _analyze_recursive(self, node: dict, analysis: dict, depth: int):
+        """Recursively analyze tree nodes."""
+        elem_type = node.get("type")
+        label = node.get("AXLabel", "")
+        value = node.get("AXValue", "")
+        identifier = node.get("AXUniqueId", "")
+
+        # Count element
+        if elem_type:
+            analysis["total_elements"] += 1
+
+            # Track by type
+            if elem_type in self.INTERACTIVE_TYPES:
+                analysis["interactive_elements"] += 1
+
+                # Store concise info (label only, not full node)
+                elem_info = label or value or identifier or "Unnamed"
+                analysis["elements_by_type"][elem_type].append(elem_info)
+
+                # Special handling for common types
+                if elem_type == "Button":
+                    analysis["buttons"].append(elem_info)
+                elif elem_type in ("TextField", "SecureTextField"):
+                    analysis["text_fields"].append(
+                        {"type": elem_type, "label": elem_info, "has_value": bool(value)}
+                    )
+                elif elem_type == "NavigationBar":
+                    analysis["navigation"]["nav_title"] = label or "Navigation"
+                elif elem_type == "TabBar":
+                    # Count tab items
+                    tab_count = len(node.get("children", []))
+                    analysis["navigation"]["tab_count"] = tab_count
+
+            # Track focusable elements
+            if node.get("enabled", False) and elem_type in self.INTERACTIVE_TYPES:
+                analysis["focusable"] += 1
+
+        # Try to identify screen name from view controller
+        if not analysis["screen_name"] and identifier:
+            if "ViewController" in identifier or "Screen" in identifier:
+                analysis["screen_name"] = identifier
+
+        # Process children
+        for child in node.get("children", []):
+            self._analyze_recursive(child, analysis, depth + 1)
+
+    def format_summary(self, analysis: dict, verbose: bool = False) -> str:
+        """Format analysis as token-efficient summary."""
+        lines = []
+
+        # Screen identification (1 line)
+        screen = analysis["screen_name"] or "Unknown Screen"
+        total = analysis["total_elements"]
+        interactive = analysis["interactive_elements"]
+        lines.append(f"Screen: {screen} ({total} elements, {interactive} interactive)")
+
+        # Buttons summary (1 line)
+        if analysis["buttons"]:
+            button_list = ", ".join(f'"{b}"' for b in analysis["buttons"][:BUTTONS_PREVIEW])
+            if len(analysis["buttons"]) > BUTTONS_PREVIEW:
+                button_list += f" +{len(analysis['buttons']) - BUTTONS_PREVIEW} more"
+            lines.append(f"Buttons: {button_list}")
+
+        # Text fields summary (1 line)
+        if analysis["text_fields"]:
+            field_count = len(analysis["text_fields"])
+            [f["type"] for f in analysis["text_fields"]]
+            filled = sum(1 for f in analysis["text_fields"] if f["has_value"])
+            lines.append(f"TextFields: {field_count} ({filled} filled)")
+
+        # Navigation summary (1 line)
+        nav_parts = []
+        if "nav_title" in analysis["navigation"]:
+            nav_parts.append(f"NavBar: \"{analysis['navigation']['nav_title']}\"")
+        if "tab_count" in analysis["navigation"]:
+            nav_parts.append(f"TabBar: {analysis['navigation']['tab_count']} tabs")
+        if nav_parts:
+            lines.append(f"Navigation: {', '.join(nav_parts)}")
+
+        # Focusable count (1 line)
+        lines.append(f"Focusable: {analysis['focusable']} elements")
+
+        # Verbose mode adds element type breakdown
+        if verbose:
+            lines.append("\nElements by type:")
+            for elem_type, items in analysis["elements_by_type"].items():
+                if items:  # Only show types that exist
+                    lines.append(f"  {elem_type}: {len(items)}")
+                    for item in items[:SECTION_ITEMS_PREVIEW]:
+                        lines.append(f"    - {item}")
+                    if len(items) > SECTION_ITEMS_PREVIEW:
+                        lines.append(f"    ... +{len(items) - SECTION_ITEMS_PREVIEW} more")
+
+        return "\n".join(lines)
+
+    def get_navigation_hints(self, analysis: dict) -> list[str]:
+        """Generate navigation hints based on screen analysis."""
+        hints = []
+
+        # Check for common patterns
+        if "Login" in str(analysis.get("buttons", [])):
+            hints.append("Login screen detected - find TextFields for credentials")
+
+        if analysis["text_fields"]:
+            unfilled = [f for f in analysis["text_fields"] if not f["has_value"]]
+            if unfilled:
+                hints.append(f"{len(unfilled)} empty text field(s) - may need input")
+
+        if not analysis["buttons"] and not analysis["text_fields"]:
+            hints.append("No interactive elements - try swiping or going back")
+
+        if "tab_count" in analysis.get("navigation", {}):
+            hints.append(f"Tab bar available with {analysis['navigation']['tab_count']} tabs")
+
+        return hints
+
+
+def main():
+    """Main entry point."""
+    parser = argparse.ArgumentParser(description="Map current screen UI elements")
+    parser.add_argument("--verbose", action="store_true", help="Show detailed element breakdown")
+    parser.add_argument("--json", action="store_true", help="Output raw JSON analysis")
+    parser.add_argument("--hints", action="store_true", help="Include navigation hints")
+    parser.add_argument(
+        "--udid",
+        help="Device UDID (auto-detects booted simulator if not provided)",
+    )
+
+    args = parser.parse_args()
+
+    # Resolve UDID with auto-detection
+    try:
+        udid = resolve_udid(args.udid)
+    except RuntimeError as e:
+        print(f"Error: {e}")
+        sys.exit(1)
+
+    # Create mapper and analyze
+    mapper = ScreenMapper(udid=udid)
+    tree = mapper.get_accessibility_tree()
+    analysis = mapper.analyze_tree(tree)
+
+    # Output based on format
+    if args.json:
+        # Full JSON (verbose)
+        print(json.dumps(analysis, indent=2, default=str))
+    else:
+        # Token-efficient summary (default)
+        summary = mapper.format_summary(analysis, verbose=args.verbose)
+        print(summary)
+
+        # Add hints if requested
+        if args.hints:
+            hints = mapper.get_navigation_hints(analysis)
+            if hints:
+                print("\nHints:")
+                for hint in hints:
+                    print(f"  - {hint}")
+
+
+if __name__ == "__main__":
+    main()

package/skills/ios-simulator-skill/scripts/sim_health_check.sh

@@ -0,0 +1,245 @@
+#!/usr/bin/env bash
+#
+# iOS Simulator Testing Environment Health Check
+#
+# Verifies that all required tools and dependencies are properly installed
+# and configured for iOS simulator testing.
+#
+# Usage: bash scripts/sim_health_check.sh [--help]
+
+set -e
+
+# Color codes for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Check flags
+SHOW_HELP=false
+
+# Parse arguments
+for arg in "$@"; do
+    case $arg in
+        --help|-h)
+            SHOW_HELP=true
+            shift
+            ;;
+    esac
+done
+
+if [ "$SHOW_HELP" = true ]; then
+    cat <<EOF
+iOS Simulator Testing - Environment Health Check
+
+Verifies that your environment is properly configured for iOS simulator testing.
+
+Usage: bash scripts/sim_health_check.sh [options]
+
+Options:
+  --help, -h    Show this help message
+
+This script checks for:
+  - Xcode Command Line Tools installation
+  - iOS Simulator availability
+  - IDB (iOS Development Bridge) installation
+  - Available simulator devices
+  - Python 3 installation (for scripts)
+
+Exit codes:
+  0 - All checks passed
+  1 - One or more checks failed (see output for details)
+EOF
+    exit 0
+fi
+
+echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo -e "${BLUE}  iOS Simulator Testing - Environment Health Check${NC}"
+echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo ""
+
+CHECKS_PASSED=0
+CHECKS_FAILED=0
+
+# Function to print check status
+check_passed() {
+    echo -e "${GREEN}✓${NC} $1"
+    CHECKS_PASSED=$((CHECKS_PASSED + 1))
+}
+
+check_failed() {
+    echo -e "${RED}✗${NC} $1"
+    CHECKS_FAILED=$((CHECKS_FAILED + 1))
+}
+
+check_warning() {
+    echo -e "${YELLOW}⚠${NC} $1"
+}
+
+# Check 1: macOS
+echo -e "${BLUE}[1/8]${NC} Checking operating system..."
+if [[ "$OSTYPE" == "darwin"* ]]; then
+    OS_VERSION=$(sw_vers -productVersion)
+    check_passed "macOS detected (version $OS_VERSION)"
+else
+    check_failed "Not running on macOS (detected: $OSTYPE)"
+    echo "       iOS Simulator testing requires macOS"
+fi
+echo ""
+
+# Check 2: Xcode Command Line Tools
+echo -e "${BLUE}[2/8]${NC} Checking Xcode Command Line Tools..."
+if command -v xcrun &> /dev/null; then
+    XCODE_PATH=$(xcode-select -p 2>/dev/null || echo "not found")
+    if [ "$XCODE_PATH" != "not found" ]; then
+        XCODE_VERSION=$(xcodebuild -version 2>/dev/null | head -n 1 || echo "Unknown")
+        check_passed "Xcode Command Line Tools installed"
+        echo "       Path: $XCODE_PATH"
+        echo "       Version: $XCODE_VERSION"
+    else
+        check_failed "Xcode Command Line Tools path not set"
+        echo "       Run: xcode-select --install"
+    fi
+else
+    check_failed "xcrun command not found"
+    echo "       Install Xcode Command Line Tools: xcode-select --install"
+fi
+echo ""
+
+# Check 3: simctl availability
+echo -e "${BLUE}[3/8]${NC} Checking simctl (Simulator Control)..."
+if command -v xcrun &> /dev/null && xcrun simctl help &> /dev/null; then
+    check_passed "simctl is available"
+else
+    check_failed "simctl not available"
+    echo "       simctl comes with Xcode Command Line Tools"
+fi
+echo ""
+
+# Check 4: IDB installation
+echo -e "${BLUE}[4/8]${NC} Checking IDB (iOS Development Bridge)..."
+if command -v idb &> /dev/null; then
+    IDB_PATH=$(which idb)
+    IDB_VERSION=$(idb --version 2>/dev/null || echo "Unknown")
+    check_passed "IDB is installed"
+    echo "       Path: $IDB_PATH"
+    echo "       Version: $IDB_VERSION"
+else
+    check_warning "IDB not found in PATH"
+    echo "       IDB is optional but provides advanced UI automation"
+    echo "       Install: https://fbidb.io/docs/installation"
+    echo "       Recommended: brew tap facebook/fb && brew install idb-companion"
+fi
+echo ""
+
+# Check 5: Python 3.12+ installation
+echo -e "${BLUE}[5/8]${NC} Checking Python 3.12+..."
+if command -v python3 &> /dev/null; then
+    PYTHON_MAJOR=$(python3 -c "import sys; print(sys.version_info.major)")
+    PYTHON_MINOR=$(python3 -c "import sys; print(sys.version_info.minor)")
+    if [ "$PYTHON_MAJOR" -lt 3 ] || { [ "$PYTHON_MAJOR" -eq 3 ] && [ "$PYTHON_MINOR" -lt 12 ]; }; then
+        check_failed "Python $PYTHON_MAJOR.$PYTHON_MINOR found — Python 3.12+ required"
+        echo "       Upgrade: brew install python@3.12"
+    else
+        check_passed "Python $PYTHON_MAJOR.$PYTHON_MINOR (>= 3.12 required)"
+    fi
+else
+    check_failed "Python 3 not found"
+    echo "       Python 3.12+ is required for testing scripts"
+    echo "       Install: brew install python@3.12"
+fi
+echo ""
+
+# Check 6: Available simulators
+echo -e "${BLUE}[6/8]${NC} Checking available iOS Simulators..."
+if command -v xcrun &> /dev/null; then
+    SIMULATOR_COUNT=$(xcrun simctl list devices available 2>/dev/null | grep -c "iPhone\|iPad" || echo "0")
+
+    if [ "$SIMULATOR_COUNT" -gt 0 ]; then
+        check_passed "Found $SIMULATOR_COUNT available simulator(s)"
+
+        # Show first 5 simulators
+        echo ""
+        echo "       Available simulators (showing up to 5):"
+        xcrun simctl list devices available 2>/dev/null | grep "iPhone\|iPad" | head -5 | while read -r line; do
+            echo "       - $line"
+        done
+    else
+        check_warning "No simulators found"
+        echo "       Create simulators via Xcode or simctl"
+        echo "       Example: xcrun simctl create 'iPhone 15' 'iPhone 15'"
+    fi
+else
+    check_failed "Cannot check simulators (simctl not available)"
+fi
+echo ""
+
+# Check 7: Booted simulators
+echo -e "${BLUE}[7/8]${NC} Checking booted simulators..."
+if command -v xcrun &> /dev/null; then
+    BOOTED_SIMS=$(xcrun simctl list devices booted 2>/dev/null | grep -c "iPhone\|iPad" || echo "0")
+
+    if [ "$BOOTED_SIMS" -gt 0 ]; then
+        check_passed "$BOOTED_SIMS simulator(s) currently booted"
+
+        echo ""
+        echo "       Booted simulators:"
+        xcrun simctl list devices booted 2>/dev/null | grep "iPhone\|iPad" | while read -r line; do
+            echo "       - $line"
+        done
+    else
+        check_warning "No simulators currently booted"
+        echo "       Boot a simulator to begin testing"
+        echo "       Example: xcrun simctl boot <device-udid>"
+        echo "       Or: open -a Simulator"
+    fi
+else
+    check_failed "Cannot check booted simulators (simctl not available)"
+fi
+echo ""
+
+# Check 8: Required Python packages (optional check)
+echo -e "${BLUE}[8/8]${NC} Checking Python packages..."
+if command -v python3 &> /dev/null; then
+    MISSING_PACKAGES=()
+
+    # Check for PIL/Pillow (for visual_diff.py)
+    if python3 -c "import PIL" 2>/dev/null; then
+        check_passed "Pillow (PIL) installed - visual diff available"
+    else
+        MISSING_PACKAGES+=("pillow")
+        check_warning "Pillow (PIL) not installed - visual diff won't work"
+    fi
+
+    if [ ${#MISSING_PACKAGES[@]} -gt 0 ]; then
+        echo ""
+        echo "       Install missing packages:"
+        echo "       pip3 install ${MISSING_PACKAGES[*]}"
+    fi
+else
+    check_warning "Cannot check Python packages (Python 3 not available)"
+fi
+echo ""
+
+# Summary
+echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo -e "${BLUE}  Summary${NC}"
+echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo ""
+echo -e "Checks passed: ${GREEN}$CHECKS_PASSED${NC}"
+if [ "$CHECKS_FAILED" -gt 0 ]; then
+    echo -e "Checks failed: ${RED}$CHECKS_FAILED${NC}"
+    echo ""
+    echo -e "${YELLOW}Action required:${NC} Fix the failed checks above before testing"
+    exit 1
+else
+    echo ""
+    echo -e "${GREEN}✓ Environment is ready for iOS simulator testing${NC}"
+    echo ""
+    echo "Next steps:"
+    echo "  1. Boot a simulator: open -a Simulator"
+    echo "  2. Launch your app: xcrun simctl launch booted <bundle-id>"
+    echo "  3. Run accessibility audit: python scripts/accessibility_audit.py"
+    exit 0
+fi