Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift
7.6 KB
Raw Blame
import ArgumentParser
import Foundation

// MARK: - Manifest values the Command can take as arguments

/// Kept here, with the other ArgumentParser conformances, rather than beside
/// the type: the manifest is a data model and has no other reason to know that
/// a command line exists.
extension VPhoneVirtualMachineManifest.PlatformFusing: ExpressibleByArgument {}

// MARK: - VPhoneBootCommand

/// The options for booting a guest.
///
/// Both binaries parse this same declaration. `vphone-vm` runs it: it builds
/// the machine and becomes the NSApplication. `vphone-cli` only *forwards* it,
/// re-rendering itself through `bootArguments` and spawning `vphone-vm`.
///
/// Keeping one declaration is what makes the two agree about `--dfu`, and
/// means `vphone-cli boot --help` and
/// `vphone-vm --help` cannot drift apart.
///
/// Note it has no `run()` that boots. `vphone-cli`'s entry point recognises
/// this command type and spawns instead, so `run()` here would only ever be a
/// trap for whoever calls it directly.
public struct VPhoneBootCommand: ParsableCommand {
    public static let configuration = CommandConfiguration(
        commandName: "boot",
        abstract: "Boot a virtual iPhone",
        discussion: """
        Creates a Virtualization.framework VM with platform version 3 (vphone)
        and boots it from a manifest plist that describes all paths and hardware.

        The VM itself runs in the companion `vphone-vm` binary, which is the only
        one signed with the private virtualization entitlements. `vphone-cli`
        carries none, so it launches normally and starts `vphone-vm` for you.

        Requires:
          - macOS 15+ (Sequoia or later)
          - SIP/AMFI disabled

        Example:
          vphone-cli --config ./config.plist
        """,
    )

    @Option(
        name: .shortAndLong,
        help: "Path to VM manifest plist (config.plist). Required.",
        transform: URL.init(fileURLWithPath:),
    )
    public var config: URL

    @Flag(name: .shortAndLong, help: "Boot into DFU mode")
    public var dfu: Bool = false

    @Flag(name: .customLong("headless"), help: "Boot without a VM window or menu bar")
    public var headless: Bool = false

    @Option(help: "Expose the guest HTTP/WebSocket API on the host, for example 127.0.0.1:8765")
    public var apiListen: String?

    @Option(help: "Kernel GDB debug stub port on host (omit for system-assigned port; valid: 6000...65535)")
    public var kernelDebugPort: Int?

    @Option(help: "Path to signed vphoned binary for guest auto-update")
    public var vphonedBin: String = ".vphoned.signed"

    @Option(
        help: "Automatically install the given IPA/TIPA after the guest control channel connects. Unavailable with --dfu.",
        transform: URL.init(fileURLWithPath:),
    )
    public var installIPA: URL?

    public init() {}

    /// Construct a forwarding command without leaving any ArgumentParser
    /// property wrapper in its undecoded definition state.
    public init(
        config: URL,
        dfu: Bool = false,
        headless: Bool = false,
        apiListen: String? = nil,
        kernelDebugPort: Int? = nil,
        vphonedBin: String = ".vphoned.signed",
        installIPA: URL? = nil,
    ) {
        self.config = config
        self.dfu = dfu
        self.headless = headless
        self.apiListen = apiListen
        self.kernelDebugPort = kernelDebugPort
        self.vphonedBin = vphonedBin
        self.installIPA = installIPA
    }

    /// DFU mode is always headless.
    public var noGraphics: Bool {
        dfu || headless
    }

    public var installPackageURL: URL? {
        installIPA?.standardizedFileURL
    }

    public mutating func validate() throws {
        let manifest = try VPhoneVirtualMachineManifest.load(from: config)
        let bundle = VPhoneBundle(url: config.deletingLastPathComponent(), manifest: manifest)
        // In DFU too: a restore would rewrite the disk every clone shares.
        try VPhoneMachineTemplates.requireBootable(bundleURL: bundle.url)
        if !dfu,
           let existingVariant = VPhoneRestoreInfo.load(fromBundle: bundle)?.variant,
           existingVariant != "jb"
        {
            throw BundleStateError(
                "This VM was created as '\(existingVariant)', which this build does not support. Create a new VM and try again.",
            )
        }
        // A restored guest without CFW panics at pid 1 and shows only a black
        // screen, so say so before booting it.
        if !dfu, VPhoneRestoreInfo.customFirmwareInstalled(inBundle: bundle) == false {
            throw BundleStateError(
                "CFW installation on this VM did not complete, so it cannot boot. Run `sudo vphone-cli cfw install \(bundle.name)`, then launch it again.",
            )
        }

        if dfu, let packageURL = installPackageURL {
            throw ValidationError(
                "`--install-ipa` is unavailable with `--dfu` because DFU mode does not start the guest control channel: \(packageURL.path)",
            )
        }

        if dfu, apiListen != nil {
            throw ValidationError("`--api-listen` is unavailable with `--dfu`.")
        }
        if let apiListen {
            let address = URLComponents(string: "tcp://\(apiListen)")
            guard let address, let host = address.host, !host.isEmpty,
                  let port = address.port, (0 ... 65535).contains(port),
                  address.path.isEmpty, address.query == nil, address.fragment == nil
            else {
                throw ValidationError("`--api-listen` requires host:port, for example 127.0.0.1:8765.")
            }
        }

        guard let packageURL = installPackageURL else { return }

        guard FileManager.default.fileExists(atPath: packageURL.path) else {
            throw ValidationError("`--install-ipa` file does not exist: \(packageURL.path)")
        }

        guard VPhoneInstallPackage.isSupportedFile(packageURL) else {
            throw ValidationError(
                "`--install-ipa` only supports .ipa or .tipa packages: \(packageURL.lastPathComponent)",
            )
        }
    }

    // MARK: - Forwarding

    /// This command rendered back into arguments for `vphone-vm`.
    ///
    /// Several callers used to hand-build this list — the launch command, and
    /// four sites in the create orchestrator — each spelling the flags out
    /// again and each free to forget one. Rendering from the parsed value keeps
    /// the spelling in the same file as the declaration, so adding an option
    /// cannot silently fail to reach the guest.
    ///
    /// The subcommand name is deliberately omitted: `vphone-vm` *is* the boot
    /// command, so its arguments start at the first option.
    public var bootArguments: [String] {
        var args = ["--config", config.path]
        if dfu {
            args.append("--dfu")
        }
        if headless {
            args.append("--headless")
        }
        if let apiListen {
            args += ["--api-listen", apiListen]
        }
        if vphonedBin != ".vphoned.signed" {
            args += ["--vphoned-bin", vphonedBin]
        }
        if let port = kernelDebugPort {
            args += ["--kernel-debug-port", String(port)]
        }
        if let ipa = installIPA {
            args += ["--install-ipa", ipa.path]
        }
        return args
    }

    /// The VM folder, not the command line, is what is wrong, so these print
    /// without the usage text a `ValidationError` brings.
    struct BundleStateError: Error, CustomStringConvertible {
        let description: String

        init(_ description: String) {
            self.description = description
        }
    }
}