Skip to content

Play your own Switch games on iPhone/iPad — one-click macOS app, no terminal. | 把 Switch 游戏装进 iPhone:图形界面一键构建,不用命令行。Bring your own game.

20.5 KB
Raw Blame
import Foundation
import CryptoKit

// The launcher's self-update, the parts that decide what may be installed and when. `AppUpdateStore` (NXModel) drives it;
// everything here works on data and paths it is given, so the tests run it on bundles in a temporary folder, never on the
// running app or the network.
//
// The rules:
//   - What is installed is what GitHub says the release is: the zip's SHA-256 matches the asset's `digest`
//     ("sha256:<hex>", in the release API since 2025), and the app inside it carries the running app's bundle
//     identifier, an executable and the release's version. An automatic install also needs the digest to be
//     there; the Update button, pressed by hand, still installs a release without one (older releases have none).
//   - Only a released copy replaces itself: a launcher built from the repository (swift run, a bundle assembled in
//     frontend/, an Xcode build) keeps the developer's build in place.
//   - Never while a build runs: the swap ends with a relaunch (exit), and a build is a process group of the app's.

package enum AppUpdate {
    /// The latest release, as the check found it.
    package struct Release: Equatable {
        package init(tag: String, url: String, digest: String?, notes: String = "") {
        self.tag = tag; self.url = url; self.digest = digest; self.notes = notes
    }
        package let tag: String
        package let url: String
        package let digest: String?   // "sha256:<hex>"; nil when the API gave none
        /// The release body, shown by the update sheet before anything is downloaded: "a new version
        /// is out" alone told a user nothing about what they would get.
        package var notes: String = ""
    }

    /// A release downloaded, verified and unpacked, waiting to be swapped in.
    package struct Staged: Equatable {
        package init(release: Release, app: URL) { self.release = release; self.app = app }
        package let release: Release
        package let app: URL
    }

    // ---- What was downloaded ----

    package enum DigestCheck: Equatable { case match, mismatch, missing }

    /// The SHA-256 of a file, as lowercase hex, read in pieces (the zip is tens of megabytes).
    package static func sha256(of file: URL) -> String? {
        guard let handle = try? FileHandle(forReadingFrom: file) else { return nil }
        defer { try? handle.close() }
        var hasher = SHA256()
        while true {
            let chunk = handle.readData(ofLength: 1 << 20)
            if chunk.isEmpty { break }
            hasher.update(data: chunk)
        }
        return hasher.finalize().map { String(format: "%02x", $0) }.joined()
    }

    /// The file against the asset's digest. A digest in any other algorithm, or none, counts as missing: there is
    /// nothing to compare with, which an automatic install refuses.
    package static func checkDigest(_ file: URL, expected: String?) -> DigestCheck {
        guard let expected, expected.lowercased().hasPrefix("sha256:") else { return .missing }
        let want = expected.dropFirst("sha256:".count).trimmingCharacters(in: .whitespaces).lowercased()
        guard want.count == 64, let have = sha256(of: file) else { return want.isEmpty ? .missing : .mismatch }
        return have == want ? .match : .mismatch
    }

    package enum BundleProblem: Error, Equatable { case noInfo, wrongIdentifier, noExecutable, wrongVersion }

    /// Whether `app` is an NX2Apple launcher of the release `tag`: the running app's bundle identifier (a zip of
    /// something else must not take its place), an executable where its Info.plist says, and the release's version
    /// (the release workflow writes the tag into the plist; another number would be a different build).
    package static func bundleProblem(_ app: URL, expectedID: String, tag: String) -> BundleProblem? {
        let contents = app.appendingPathComponent("Contents")
        guard let data = try? Data(contentsOf: contents.appendingPathComponent("Info.plist")),
              let info = try? PropertyListSerialization.propertyList(from: data, format: nil) as? [String: Any]
        else { return .noInfo }
        guard !expectedID.isEmpty, info["CFBundleIdentifier"] as? String == expectedID else { return .wrongIdentifier }
        guard let exe = info["CFBundleExecutable"] as? String, !exe.isEmpty, !exe.contains("/"),
              FileManager.default.isExecutableFile(atPath: contents.appendingPathComponent("MacOS/" + exe).path)
        else { return .noExecutable }
        let version = tag.hasPrefix("v") ? String(tag.dropFirst()) : tag
        guard info["CFBundleShortVersionString"] as? String == version else { return .wrongVersion }
        return nil
    }

    // ---- What the running macOS can open ----

    /// "26.6" or "26.6.1" as an OS version; nil for anything else.
    package static func parseOSVersion(_ s: String) -> OperatingSystemVersion? {
        let n = s.trimmingCharacters(in: .whitespaces).split(separator: ".", omittingEmptySubsequences: false).map { Int($0) }
        guard (1...3).contains(n.count), n.allSatisfy({ $0 != nil && $0! >= 0 }) else { return nil }
        return OperatingSystemVersion(majorVersion: n[0]!, minorVersion: n.count > 1 ? n[1]! : 0, patchVersion: n.count > 2 ? n[2]! : 0)
    }

    /// `a` is older than `b`, field by field (major, minor, patch).
    package static func isOlder(_ a: OperatingSystemVersion, than b: OperatingSystemVersion) -> Bool {
        (a.majorVersion, a.minorVersion, a.patchVersion) < (b.majorVersion, b.minorVersion, b.patchVersion)
    }

    package static func describe(_ v: OperatingSystemVersion) -> String {
        v.patchVersion == 0 ? "\(v.majorVersion).\(v.minorVersion)" : "\(v.majorVersion).\(v.minorVersion).\(v.patchVersion)"
    }

    /// The staged app's `LSMinimumSystemVersion`, as written ("26.6"), when it is above `running`: the release cannot be
    /// opened on this Mac, so it must not replace the launcher that can. nil when it opens here, or names no minimum
    /// (macOS then applies none) or one that cannot be read (the release workflow writes it; an unreadable value is
    /// not a reason to keep a Mac from updating).
    package static func minimumOSAbove(_ running: OperatingSystemVersion, app: URL) -> String? {
        guard let data = try? Data(contentsOf: app.appendingPathComponent("Contents/Info.plist")),
              let info = try? PropertyListSerialization.propertyList(from: data, format: nil) as? [String: Any],
              let text = info["LSMinimumSystemVersion"] as? String, let min = parseOSVersion(text)
        else { return nil }
        return isOlder(running, than: min) ? describe(min) : nil
    }

    // ---- What may replace itself ----

    package enum Installability: Equatable {
        case ok
        case developer   // built from the repository: never replaces itself
        case readOnly    // a released copy that cannot be replaced where it is (translocated, or a folder without write access)
    }

    /// Whether the launcher at `bundle` may replace itself. A released copy is an `.app` whose Info.plist has a bundle
    /// identifier and, as its version, this binary's own release number (the release workflow stops when the two
    /// differ), and which is not where a developer's build sits: in SwiftPM's .build, Xcode's DerivedData, or beside
    /// the Package.swift it was built from (frontend/NX2Apple.app, which the README's own recipe makes). `swift run`
    /// runs a bare executable with no bundle at all.
    package static func installability(_ bundle: URL, appVersion: String) -> Installability {
        let path = bundle.standardizedFileURL.path
        guard bundle.pathExtension == "app" else { return .developer }
        let parts = bundle.standardizedFileURL.pathComponents
        if parts.contains(".build") || parts.contains("DerivedData") { return .developer }
        let parent = bundle.standardizedFileURL.deletingLastPathComponent()
        if FileManager.default.fileExists(atPath: parent.appendingPathComponent("Package.swift").path) { return .developer }
        guard isReleaseVersion(appVersion),
              let data = try? Data(contentsOf: bundle.appendingPathComponent("Contents/Info.plist")),
              let info = try? PropertyListSerialization.propertyList(from: data, format: nil) as? [String: Any],
              let id = info["CFBundleIdentifier"] as? String, !id.isEmpty,
              info["CFBundleShortVersionString"] as? String == appVersion
        else { return .developer }
        // Gatekeeper runs a quarantined app opened from Downloads from a read-only copy: the swap cannot reach the real one
        if path.contains("/AppTranslocation/") { return .readOnly }
        if !FileManager.default.isWritableFile(atPath: parent.path) { return .readOnly }
        return .ok
    }

    /// "1.2.3": digits and dots, nothing else (a dev build might say "dev", "0.0.0-local" or nothing).
    package static func isReleaseVersion(_ v: String) -> Bool {
        let parts = v.split(separator: ".", omittingEmptySubsequences: false)
        return parts.count >= 2 && parts.allSatisfy { !$0.isEmpty && $0.allSatisfy(\.isASCII) && $0.allSatisfy(\.isNumber) }
    }

    // ---- When ----

    package enum InstallError: Error, Equatable { case buildRunning, failed(String) }

    /// Swap `staged` in at `current`: copied in beside it first (from there on every step stays on one volume), then
    /// exchanged with it in one replace, so a failure anywhere leaves a working app at `current`. The old bundle goes
    /// to the Trash (`trashOld`; the tests remove it instead), and the new one loses the quarantine flag, so its first
    /// launch shows no Gatekeeper prompt (the release is ad-hoc signed, not notarized).
    ///
    /// Refused while a build runs: the caller relaunches (or the app is quitting), and either ends the build's process group.
    /// Where the staged release goes: its own bundle name when it differs from the running copy's,
    /// else the current URL.
    ///
    /// The two-name case is a rename era (nxnative → NS Port Builder → NX2Apple). Replacing in place
    /// would keep the old folder's name for ever: the app inside is the new version, but the
    /// Finder, the Dock and /Applications keep saying the old name, which read as "the update did
    /// not happen" (a 0.4.6 install updated to 0.4.8 and still saw NS Port Builder). Under the new
    /// name the old bundle is removed; the Dock entry pointing at it goes stale once, which a log
    /// line names — the alternative was the old name for ever.
    package static func installTarget(for staged: URL, current: URL) -> URL {
        staged.lastPathComponent == current.lastPathComponent
            ? current
            : current.deletingLastPathComponent().appendingPathComponent(staged.lastPathComponent)
    }

    /// Install the staged app and return where it ended up (the caller relaunches that path).
    package static func install(_ staged: URL, over current: URL, buildRunning: Bool, trashOld: Bool = true,
                                runner: ProcessRunner = SystemProcessRunner()) throws -> URL {
        guard !buildRunning else { throw InstallError.buildRunning }
        let fm = FileManager.default
        let dir = current.deletingLastPathComponent()
        let target = installTarget(for: staged, current: current)
        if target != current {
            // A rename: place the staged bundle under its own name, then retire the old-named one.
            // The running copy is trashed last — on macOS a running executable survives the removal
            // of its bundle (the kernel holds the vnode), and the quit-time path runs this as the
            // app is exiting anyway.
            try? fm.removeItem(at: target)
            try fm.copyItem(at: staged, to: target)
            clearQuarantine(target, runner: runner)
            if trashOld { try? fm.trashItem(at: current, resultingItemURL: nil) }
            return target
        }
        let name = current.deletingPathExtension().lastPathComponent
        let incoming = dir.appendingPathComponent(name + " (new).app")
        let backupName = name + " (old).app"
        try? fm.removeItem(at: incoming)
        try? fm.removeItem(at: dir.appendingPathComponent(backupName))
        do {
            try fm.copyItem(at: staged, to: incoming)
            let placed = try fm.replaceItemAt(current, withItemAt: incoming, backupItemName: backupName, options: [.withoutDeletingBackupItem])
            let backup = dir.appendingPathComponent(backupName)
            if fm.fileExists(atPath: backup.path) {
                if trashOld { try? fm.trashItem(at: backup, resultingItemURL: nil) } else { try? fm.removeItem(at: backup) }
            }
            clearQuarantine(placed ?? current, runner: runner)
            return current
        } catch {
            try? fm.removeItem(at: incoming)
            throw InstallError.failed(error.localizedDescription)
        }
    }

    /// The shell script behind `relaunch`: wait until `$1` (a pid) has exited, at most `$3` ticks of 0.2 s,
    /// then open `$2` with `$4`. The paths arrive as arguments, never spliced into the script, so spaces and
    /// quotes in them are safe.
    package static let relaunchScript = """
        n=0
        while kill -0 "$1" 2>/dev/null && [ "$n" -lt "$3" ]; do sleep 0.2; n=$((n+1)); done
        sleep 0.5
        exec "$4" "$2"
        """

    /// Start the new copy once this one is gone. `NSWorkspace.openApplication` cannot do it while the old
    /// instance runs: LaunchServices finds the same bundle id and only activates that instance. So a detached
    /// shell waits for the pid to exit, then runs `open`. The caller terminates the app right after.
    @discardableResult
    package static func relaunch(_ app: URL, afterExitOf pid: Int32 = ProcessInfo.processInfo.processIdentifier,
                         timeout: TimeInterval = 30, opener: String = "/usr/bin/open") -> Bool {
        let p = Process()
        p.executableURL = URL(fileURLWithPath: "/bin/sh")
        p.arguments = ["-c", relaunchScript, "sh", String(pid), app.path, String(Int(timeout / 0.2)), opener]
        p.standardInput = FileHandle.nullDevice
        p.standardOutput = FileHandle.nullDevice
        p.standardError = FileHandle.nullDevice
        do { try p.run(); return true } catch { return false }
    }

    private static func clearQuarantine(_ app: URL, runner: ProcessRunner) {
        _ = runner.capture(ProcessLaunch(executable: "/usr/bin/xattr", arguments: ["-dr", "com.apple.quarantine", app.path]))
    }

    // ---- Which release is the latest ----

    /// The download names this build accepts, newest first. Every release must carry at least one of
    /// them or an install from that era cannot update itself: NX2Apple is current, nxnative is for
    /// installs from before the rename to NX2Apple, NS-Port-Builder for installs before that.
    package static let assetNames = ["NX2Apple-macOS-arm64.zip", "nxnative-macOS-arm64.zip", "NS-Port-Builder-macOS-arm64.zip"]

    /// `tag` ("v0.4.10") is a later version than `current` ("0.4.8"), compared number by number.
    package static func isNewer(_ tag: String, than current: String) -> Bool {
        func nums(_ s: String) -> [Int] { s.split(separator: ".").map { Int($0.filter { $0.isNumber }) ?? 0 } }
        let a = nums(tag), b = nums(current)
        for i in 0..<max(a.count, b.count) {
            let x = i < a.count ? a[i] : 0, y = i < b.count ? b[i] : 0
            if x != y { return x > y }
        }
        return false
    }

    /// The release's asset this app installs, with its digest: NX2Apple-macOS-arm64.zip, or the zip under an older
    /// name (releases from before each rename).
    package static func release(fromJSON obj: [String: Any]) -> Release? {
        let tag = obj["tag_name"] as? String ?? ""
        guard let assets = obj["assets"] as? [[String: Any]] else { return nil }
        for name in assetNames {
            for a in assets where (a["name"] as? String) == name {
                if let u = a["browser_download_url"] as? String { return Release(tag: tag, url: u, digest: a["digest"] as? String) }
            }
        }
        return nil
    }

    /// What the check of the latest release found.
    package enum Check: Equatable {
        /// The answer never came (no network, a timeout).
        case unreachable
        case upToDate
        /// A newer release exists, with the asset this app installs and the notes.
        case found(Release)
        /// A newer release exists but carries no download this build can name. That is NOT "up to date": it is the
        /// difference between a user who updates and one who sits on 0.4.6 for ever, because 0.4.6 and 0.4.7 look for
        /// exactly "NS-Port-Builder-macOS-arm64.zip" and would report "up to date" and stop.
        case noAsset(tag: String)
    }

    /// The answer of GitHub's "latest release" call (`nil` when there was none) against the running version.
    package static func check(latest data: Data?, current: String) -> Check {
        guard let data else { return .unreachable }
        guard let obj = try? JSONSerialization.jsonObject(with: data) as? [String: Any] else { return .upToDate }
        let tag = obj["tag_name"] as? String ?? ""
        guard isNewer(tag, than: current) else { return .upToDate }
        guard var r = release(fromJSON: obj) else { return .noAsset(tag: tag) }
        r.notes = (obj["body"] as? String) ?? ""
        return .found(r)
    }

    // ---- What was downloaded, to a staged app ----

    /// Why staging stopped: each case is the localization key of its message (a format with the release's tag).
    package enum StageFailure: Error, Equatable {
        case network, noDigest, mismatch, unpack, notOurApp
        /// The release's LSMinimumSystemVersion is above the running macOS (the string is that minimum).
        case needsNewerMacOS(String)

        package var key: String {
            switch self {
            case .network: return "app.stageNetFail"
            case .noDigest: return "app.noDigest"
            case .mismatch: return "app.digestMismatch"
            case .unpack: return "app.unpackFail"
            case .notOurApp: return "app.notOurApp"
            case .needsNewerMacOS: return "app.needsNewerMacOS"
            }
        }
    }

    /// The folder staging works in, in the temporary directory and emptied first.
    package static func freshStagingRoot(in temporary: URL = FileManager.default.temporaryDirectory) -> URL {
        let fm = FileManager.default
        let root = temporary.appendingPathComponent("nspb-update", isDirectory: true)
        try? fm.removeItem(at: root)
        try? fm.createDirectory(at: root, withIntermediateDirectories: true)
        return root
    }

    /// A downloaded zip to a staged app: its digest first, then unzip (ditto, as the release was packed), then the app inside.
    package static func stage(zip: URL, release: Release, in root: URL, expectedID: String, requireDigest: Bool,
                              runningOS: OperatingSystemVersion = ProcessInfo.processInfo.operatingSystemVersion,
                              runner: ProcessRunner = SystemProcessRunner()) -> Result<Staged, StageFailure> {
        let fm = FileManager.default
        switch checkDigest(zip, expected: release.digest) {
        case .match: break
        case .mismatch: try? fm.removeItem(at: zip); return .failure(.mismatch)
        case .missing: if requireDigest { try? fm.removeItem(at: zip); return .failure(.noDigest) }
        }
        let dir = root.appendingPathComponent("app", isDirectory: true)
        try? fm.removeItem(at: dir)
        try? fm.createDirectory(at: dir, withIntermediateDirectories: true)
        let unzip = runner.capture(ProcessLaunch(executable: "/usr/bin/ditto", arguments: ["-x", "-k", zip.path, dir.path]))
        guard unzip.started else { return .failure(.unpack) }
        try? fm.removeItem(at: zip)
        // The archive holds one app: NX2Apple.app, or the bundle under an older name in a release from before a rename
        guard unzip.status == 0,
              let app = ((try? fm.contentsOfDirectory(at: dir, includingPropertiesForKeys: nil)) ?? []).first(where: { $0.pathExtension == "app" })
        else { return .failure(.unpack) }
        if bundleProblem(app, expectedID: expectedID, tag: release.tag) != nil {
            try? fm.removeItem(at: dir)
            return .failure(.notOurApp)
        }
        // Not a release this Mac cannot open: it would replace a launcher that works with an app that will not start
        if let min = minimumOSAbove(runningOS, app: app) {
            try? fm.removeItem(at: dir)
            return .failure(.needsNewerMacOS(min))
        }
        return .success(Staged(release: release, app: app))
    }
}