pymobiledevice3 4.14.6__py3-none-any.whl → 7.0.6__py3-none-any.whl

pymobiledevice3/cli/developer/core_device.py

@@ -0,0 +1,294 @@
+import asyncio
+import logging
+import posixpath
+import time
+from pathlib import Path
+from typing import IO, Annotated, Optional
+
+import click
+import typer
+from typer_injector import InjectingTyper
+
+from pymobiledevice3.cli.cli_common import RSDServiceProviderDep, print_json
+from pymobiledevice3.lockdown import create_using_usbmux
+from pymobiledevice3.remote.core_device.app_service import AppServiceService
+from pymobiledevice3.remote.core_device.device_info import DeviceInfoService
+from pymobiledevice3.remote.core_device.diagnostics_service import DiagnosticsServiceService
+from pymobiledevice3.remote.core_device.file_service import APPLE_DOMAIN_DICT, FileServiceService
+from pymobiledevice3.remote.remote_service_discovery import RemoteServiceDiscoveryService
+from pymobiledevice3.services.crash_reports import CrashReportsManager
+from pymobiledevice3.utils import try_decode
+
+logger = logging.getLogger(__name__)
+
+
+cli = InjectingTyper(
+    name="core-device",
+    help="Access DeveloperDiskImage services (files, processes, app launch, diagnostics).",
+    no_args_is_help=True,
+)
+
+
+async def core_device_list_directory_task(
+    service_provider: RemoteServiceDiscoveryService, domain: str, path: str, identifier: str
+) -> None:
+    async with FileServiceService(service_provider, APPLE_DOMAIN_DICT[domain], identifier) as file_service:
+        print_json(await file_service.retrieve_directory_list(path))
+
+
+@cli.command("list-directory")
+def core_device_list_directory(
+    service_provider: RSDServiceProviderDep,
+    domain: Annotated[
+        str,
+        typer.Argument(click_type=click.Choice(APPLE_DOMAIN_DICT)),
+    ],
+    path: str,
+    identifier: Annotated[str, typer.Option()] = "",
+) -> None:
+    """List directory contents for a given domain/path."""
+    asyncio.run(core_device_list_directory_task(service_provider, domain, path, identifier))
+
+
+async def core_device_read_file_task(
+    service_provider: RemoteServiceDiscoveryService,
+    domain: str,
+    path: str,
+    identifier: str,
+    output: Optional[IO],
+) -> None:
+    async with FileServiceService(service_provider, APPLE_DOMAIN_DICT[domain], identifier) as file_service:
+        buf = await file_service.retrieve_file(path)
+        if output is not None:
+            output.write(buf)
+        else:
+            print(try_decode(buf))
+
+
+@cli.command("read-file")
+def core_device_read_file(
+    service_provider: RSDServiceProviderDep,
+    domain: Annotated[
+        str,
+        typer.Argument(click_type=click.Choice(APPLE_DOMAIN_DICT)),
+    ],
+    path: str,
+    *,
+    identifier: Annotated[str, typer.Option()] = "",
+    output: Annotated[
+        Path,
+        typer.Option("--output", "-o"),
+    ],
+) -> None:
+    """Read a file from a domain/path to stdout or --output."""
+    with output.open("wb") as output_file:
+        asyncio.run(core_device_read_file_task(service_provider, domain, path, identifier, output_file))
+
+
+async def core_device_propose_empty_file_task(
+    service_provider: RemoteServiceDiscoveryService,
+    domain: str,
+    path: str,
+    identifier: str,
+    file_permissions: int,
+    uid: int,
+    gid: int,
+    creation_time: int,
+    last_modification_time: int,
+) -> None:
+    async with FileServiceService(service_provider, APPLE_DOMAIN_DICT[domain], identifier) as file_service:
+        await file_service.propose_empty_file(path, file_permissions, uid, gid, creation_time, last_modification_time)
+
+
+@cli.command("propose-empty-file")
+def core_device_propose_empty_file(
+    service_provider: RSDServiceProviderDep,
+    domain: Annotated[
+        str,
+        typer.Argument(click_type=click.Choice(APPLE_DOMAIN_DICT)),
+    ],
+    path: str,
+    identifier: Annotated[str, typer.Option()] = "",
+    file_permissions: Annotated[int, typer.Option()] = 0o644,
+    uid: Annotated[int, typer.Option()] = 501,
+    gid: Annotated[int, typer.Option()] = 501,
+    creation_time: Annotated[Optional[int], typer.Option()] = None,
+    last_modification_time: Annotated[Optional[int], typer.Option()] = None,
+) -> None:
+    """Create an empty file at the given domain/path with custom permissions/owner/timestamps."""
+    asyncio.run(
+        core_device_propose_empty_file_task(
+            service_provider,
+            domain,
+            path,
+            identifier,
+            file_permissions,
+            uid,
+            gid,
+            creation_time if creation_time is not None else int(time.time()),
+            last_modification_time if last_modification_time is not None else int(time.time()),
+        )
+    )
+
+
+async def core_device_list_launch_application_task(
+    service_provider: RemoteServiceDiscoveryService,
+    bundle_identifier: str,
+    argument: list[str],
+    kill_existing: bool,
+    suspended: bool,
+    env: dict[str, str],
+) -> None:
+    async with AppServiceService(service_provider) as app_service:
+        print_json(await app_service.launch_application(bundle_identifier, argument, kill_existing, suspended, env))
+
+
+@cli.command("launch-application")
+def core_device_launch_application(
+    service_provider: RSDServiceProviderDep,
+    bundle_identifier: str,
+    argument: list[str],
+    kill_existing: Annotated[
+        bool,
+        typer.Option(help="Whether to kill an existing instance of this process"),
+    ] = True,
+    suspended: Annotated[bool, typer.Option(help="Same as WaitForDebugger")] = False,
+    env: Annotated[
+        Optional[list[str]],
+        typer.Option(
+            help="Environment variable to pass to process given as key=value (can be specified multiple times)"
+        ),
+    ] = None,
+) -> None:
+    """Launch an app; optionally kill existing, wait for debugger, or set env vars."""
+    asyncio.run(
+        core_device_list_launch_application_task(
+            service_provider,
+            bundle_identifier,
+            list(argument),
+            kill_existing,
+            suspended,
+            dict(var.split("=", 1) for var in env or ()),
+        )
+    )
+
+
+async def core_device_list_processes_task(service_provider: RemoteServiceDiscoveryService) -> None:
+    async with AppServiceService(service_provider) as app_service:
+        print_json(await app_service.list_processes())
+
+
+@cli.command("list-processes")
+def core_device_list_processes(service_provider: RSDServiceProviderDep) -> None:
+    """List running processes via CoreDevice."""
+    asyncio.run(core_device_list_processes_task(service_provider))
+
+
+async def core_device_uninstall_app_task(
+    service_provider: RemoteServiceDiscoveryService, bundle_identifier: str
+) -> None:
+    async with AppServiceService(service_provider) as app_service:
+        await app_service.uninstall_app(bundle_identifier)
+
+
+@cli.command("uninstall")
+def core_device_uninstall_app(service_provider: RSDServiceProviderDep, bundle_identifier: str) -> None:
+    """Uninstall an app by bundle identifier via CoreDevice."""
+    asyncio.run(core_device_uninstall_app_task(service_provider, bundle_identifier))
+
+
+async def core_device_send_signal_to_process_task(
+    service_provider: RemoteServiceDiscoveryService, pid: int, signal: int
+) -> None:
+    async with AppServiceService(service_provider) as app_service:
+        print_json(await app_service.send_signal_to_process(pid, signal))
+
+
+@cli.command("send-signal-to-process")
+def core_device_send_signal_to_process(service_provider: RSDServiceProviderDep, pid: int, signal: int) -> None:
+    """Send signal to process"""
+    asyncio.run(core_device_send_signal_to_process_task(service_provider, pid, signal))
+
+
+async def core_device_get_device_info_task(service_provider: RemoteServiceDiscoveryService) -> None:
+    async with DeviceInfoService(service_provider) as app_service:
+        print_json(await app_service.get_device_info())
+
+
+@cli.command("get-device-info")
+def core_device_get_device_info(service_provider: RSDServiceProviderDep) -> None:
+    """Get device information"""
+    asyncio.run(core_device_get_device_info_task(service_provider))
+
+
+async def core_device_get_display_info_task(service_provider: RemoteServiceDiscoveryService) -> None:
+    async with DeviceInfoService(service_provider) as app_service:
+        print_json(await app_service.get_display_info())
+
+
+@cli.command("get-display-info")
+def core_device_get_display_info(service_provider: RSDServiceProviderDep) -> None:
+    """Get display information"""
+    asyncio.run(core_device_get_display_info_task(service_provider))
+
+
+async def core_device_query_mobilegestalt_task(service_provider: RemoteServiceDiscoveryService, key: list[str]) -> None:
+    """Query MobileGestalt"""
+    async with DeviceInfoService(service_provider) as app_service:
+        print_json(await app_service.query_mobilegestalt(key))
+
+
+@cli.command("query-mobilegestalt")
+def core_device_query_mobilegestalt(service_provider: RSDServiceProviderDep, key: list[str]) -> None:
+    """Query MobileGestalt"""
+    asyncio.run(core_device_query_mobilegestalt_task(service_provider, key))
+
+
+async def core_device_get_lockstate_task(service_provider: RemoteServiceDiscoveryService) -> None:
+    async with DeviceInfoService(service_provider) as app_service:
+        print_json(await app_service.get_lockstate())
+
+
+@cli.command("get-lockstate")
+def core_device_get_lockstate(service_provider: RSDServiceProviderDep) -> None:
+    """Get lockstate"""
+    asyncio.run(core_device_get_lockstate_task(service_provider))
+
+
+async def core_device_list_apps_task(service_provider: RemoteServiceDiscoveryService) -> None:
+    async with AppServiceService(service_provider) as app_service:
+        print_json(await app_service.list_apps())
+
+
+@cli.command("list-apps")
+def core_device_list_apps(service_provider: RSDServiceProviderDep) -> None:
+    """Get application list"""
+    asyncio.run(core_device_list_apps_task(service_provider))
+
+
+async def core_device_sysdiagnose_task(service_provider: RemoteServiceDiscoveryService, output: Path) -> None:
+    async with DiagnosticsServiceService(service_provider) as service:
+        response = await service.capture_sysdiagnose(False)
+        logger.info(f"Operation response: {response}")
+        if output.is_dir():
+            output /= response.preferred_filename
+        logger.info(f"Downloading sysdiagnose to: {output}")
+
+        # get the file over lockdownd which is WAYYY faster
+        lockdown = create_using_usbmux(service_provider.udid)
+        with CrashReportsManager(lockdown) as crash_reports_manager:
+            crash_reports_manager.afc.pull(
+                posixpath.join(f"/DiagnosticLogs/sysdiagnose/{response.preferred_filename}"), str(output)
+            )
+
+
+@cli.command("sysdiagnose")
+def core_device_sysdiagnose(
+    service_provider: RSDServiceProviderDep,
+    output: Annotated[
+        Path,
+        typer.Argument(dir_okay=True, file_okay=True, exists=True),
+    ],
+) -> None:
+    """Execute sysdiagnose and fetch the output file"""
+    asyncio.run(core_device_sysdiagnose_task(service_provider, output))

pymobiledevice3/cli/developer/debugserver.py

@@ -0,0 +1,244 @@
+import logging
+import os
+import plistlib
+import signal
+import struct
+import subprocess
+import sys
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+from packaging.version import Version
+from plumbum import local
+from typer_injector import InjectingTyper
+
+from pymobiledevice3.cli.cli_common import RSDServiceProviderDep, ServiceProviderDep, print_json
+from pymobiledevice3.exceptions import RSDRequiredError
+from pymobiledevice3.lockdown import create_using_usbmux
+from pymobiledevice3.remote.remote_service_discovery import RemoteServiceDiscoveryService
+from pymobiledevice3.services.debugserver_applist import DebugServerAppList
+from pymobiledevice3.services.installation_proxy import InstallationProxyService
+from pymobiledevice3.tcp_forwarder import LockdownTcpForwarder
+
+DEBUGSERVER_CONNECTION_STEPS = """
+Follow the following connections steps from LLDB:
+
+(lldb) platform select remote-ios
+(lldb) target create /path/to/local/application.app
+(lldb) script lldb.target.module[0].SetPlatformFileSpec(lldb.SBFileSpec('/private/var/containers/Bundle/Application/<APP-UUID>/application.app'))
+(lldb) process connect connect://[{host}]:{port}   <-- ACTUAL CONNECTION DETAILS!
+(lldb) process launch
+"""
+
+
+logger = logging.getLogger(__name__)
+
+
+cli = InjectingTyper(
+    name="debugserver",
+    help="Start and drive debugserver sessions (RSD for iOS 17+, usbmux for older).",
+    no_args_is_help=True,
+)
+
+
+@cli.command("applist")
+def debugserver_applist(service_provider: ServiceProviderDep) -> None:
+    """Print the debugserver applist XML for the device."""
+    print_json(DebugServerAppList(service_provider).get())
+
+
+@cli.command("start-server")
+def debugserver_start_server(service_provider: ServiceProviderDep, local_port: Optional[int] = None) -> None:
+    """
+    Start debugserver and print the LLDB connect string.
+
+    - For iOS < 17, you must forward to a local port (--local-port).
+    - For iOS >= 17, if connected over RSD, the remote host:port is printed for LLDB.
+    Connect quickly with your own LLDB client using the printed steps.
+    """
+
+    if Version(service_provider.product_version) < Version("17.0"):
+        service_name = "com.apple.debugserver.DVTSecureSocketProxy"
+    else:
+        service_name = "com.apple.internal.dt.remote.debugproxy"
+
+    if local_port is not None:
+        print(DEBUGSERVER_CONNECTION_STEPS.format(host="127.0.0.1", port=local_port))
+        print("Started port forwarding. Press Ctrl-C to close this shell when done")
+        sys.stdout.flush()
+        LockdownTcpForwarder(service_provider, local_port, service_name).start()
+    elif Version(service_provider.product_version) >= Version("17.0"):
+        if not isinstance(service_provider, RemoteServiceDiscoveryService):
+            raise RSDRequiredError(service_provider.identifier)
+        debugserver_port = service_provider.get_service_port(service_name)
+        print(DEBUGSERVER_CONNECTION_STEPS.format(host=service_provider.service.address[0], port=debugserver_port))
+    else:
+        print("local_port is required for iOS < 17.0")
+
+
+@cli.command("lldb")
+def debugserver_lldb(
+    service_provider: RSDServiceProviderDep,
+    xcodeproj_path: Annotated[
+        Path,
+        typer.Argument(exists=True, file_okay=False, dir_okay=True),
+    ],
+    configuration: Annotated[
+        str,
+        typer.Option(help="Build configuration to invoke (e.g., Debug or Release)."),
+    ] = "Debug",
+    lldb_command: Annotated[
+        str,
+        typer.Option(help="Path to the lldb executable to run."),
+    ] = "lldb",
+    launch: Annotated[
+        bool,
+        typer.Option(help="Automatically launch the app after attaching."),
+    ] = False,
+    breakpoints: Annotated[
+        Optional[list[str]],
+        typer.Option("--break", "-b", help="Add multiple startup breakpoints"),
+    ] = None,
+    user_commands: Annotated[
+        Optional[list[str]],
+        typer.Option("--command", "-c", help="Additional commands to run at startup"),
+    ] = None,
+) -> None:
+    """
+    Automate lldb launch for a given xcodeproj.
+
+    \b
+    This will:
+    - Build the given xcodeproj
+    - Install it
+    - Start a debugserver attached to it
+    - Place breakpoints if given any
+    - Launch the application if requested
+    - Execute any additional commands if requested
+    - Switch to lldb shell
+    """
+    if Version(service_provider.product_version) < Version("17.0"):
+        logger.error("lldb is only supported on iOS >= 17.0")
+        return
+
+    commands = []
+    with local.cwd(xcodeproj_path.parent):
+        logger.info(f"Building {xcodeproj_path} for {configuration} configuration")
+        local["xcodebuild"]["-configuration", configuration, "build"]()
+        local_app = next(iter(Path(f"build/{configuration}-iphoneos").glob("*.app")))
+        logger.info(f"Using app: {local_app}")
+
+        info_plist_path = local_app / "Info.plist"
+        info_plist = plistlib.loads(info_plist_path.read_bytes())
+        bundle_identifier = info_plist["CFBundleIdentifier"]
+        logger.info(f"Bundle identifier: {bundle_identifier}")
+
+        commands.append("platform select remote-ios")
+        commands.append(f'target create "{local_app.absolute()}"')
+
+        with InstallationProxyService(create_using_usbmux()) as installation_proxy:
+            logger.info("Installing app")
+            installation_proxy.install_from_local(local_app)
+            remote_path = installation_proxy.get_apps(bundle_identifiers=[bundle_identifier])[bundle_identifier]["Path"]
+            logger.info(f"Remote path: {remote_path}")
+
+        commands.append(f'script lldb.target.module[0].SetPlatformFileSpec(lldb.SBFileSpec("{remote_path}"))')
+
+        debugserver_port = service_provider.get_service_port("com.apple.internal.dt.remote.debugproxy")
+
+        # Add connection and launch commands
+        commands.append(f"process connect connect://[{service_provider.service.address[0]}]:{debugserver_port}")
+
+        if breakpoints:
+            for bp in breakpoints:
+                commands.append(f'breakpoint set -n "{bp}"')
+
+        if launch:
+            commands.append("process launch")
+
+        if user_commands:
+            # Add user commands
+            commands += user_commands
+
+        logger.info("Starting lldb with automated setup and connection")
+
+        # Works only on unix-based systems, so keep these imports here
+        import fcntl
+        import pty
+        import select as select_module
+        import termios
+        import tty
+
+        master, slave = pty.openpty()
+
+        process = None  # Initialize process variable for signal handler
+
+        # Copy terminal size from the current terminal to PTY
+        def resize_pty() -> None:
+            """Update PTY size to match current terminal size"""
+            size = struct.unpack(
+                "HHHH", fcntl.ioctl(sys.stdout.fileno(), termios.TIOCGWINSZ, struct.pack("HHHH", 0, 0, 0, 0))
+            )
+            fcntl.ioctl(master, termios.TIOCSWINSZ, struct.pack("HHHH", *size))
+            # Send SIGWINCH to the child process to notify it of the resize
+            if process is not None and process.poll() is None:
+                process.send_signal(signal.SIGWINCH)
+
+        # Initial resize
+        resize_pty()
+
+        # Set up signal handler for window resize
+        def handle_sigwinch(signum, frame):
+            resize_pty()
+
+        old_sigwinch_handler = signal.signal(signal.SIGWINCH, handle_sigwinch)
+
+        # Save original terminal settings
+        old_tty = termios.tcgetattr(sys.stdin)
+
+        try:
+            # Set TERM environment variable to enable colors
+            env = os.environ.copy()
+            env["TERM"] = os.environ.get("TERM", "xterm-256color")
+
+            process = subprocess.Popen([lldb_command], stdin=slave, stdout=slave, stderr=slave, env=env)
+            os.close(slave)
+
+            # Put terminal in raw mode for proper interaction
+            tty.setraw(sys.stdin.fileno())
+            # Send all commands through stdin
+            for command in commands:
+                os.write(master, (command + "\n").encode())
+
+            # Now redirect stdin from the terminal to lldb so user can interact
+            while True:
+                rlist, _, _ = select_module.select([sys.stdin, master], [], [])
+
+                if sys.stdin in rlist:
+                    # User typed something
+                    data = os.read(sys.stdin.fileno(), 1024)
+                    if not data:
+                        break
+                    os.write(master, data)
+
+                if master in rlist:
+                    # lldb has output
+                    try:
+                        data = os.read(master, 1024)
+                        if not data:
+                            break
+                        os.write(sys.stdout.fileno(), data)
+                    except OSError:
+                        break
+        except (KeyboardInterrupt, OSError):
+            pass
+        finally:
+            # Restore terminal settings
+            termios.tcsetattr(sys.stdin, termios.TCSADRAIN, old_tty)
+            # Restore original SIGWINCH handler
+            signal.signal(signal.SIGWINCH, old_sigwinch_handler)
+            os.close(master)
+            if process is not None:
+                process.terminate()
+                process.wait()