Skip to content

Run Windows games on Apple Silicon — free, open source, with an open compatibility database that tells you what actually works.

32.2 KB
Raw Blame
import Foundation

/// Installs and launches Epic Games titles through Legendary (github.com/legendary-gl/legendary),
/// bypassing the Epic launcher's install flow, which cannot pass its permission audit under Wine
/// (issue #14; the launcher audits Windows ACLs Wine does not persist). Legendary is GPL-3 like
/// Highball, maintained by the Heroic team, and authenticates with the user's own Epic account.
public struct EpicStore: Sendable {
    public let paths: HighballPaths
    public init(paths: HighballPaths = HighballPaths()) { self.paths = paths }

    // Pinned like an engine component. Update deliberately, never float.
    static let binaryURL = URL(string: "https://github.com/legendary-gl/legendary/releases/download/0.21.0/legendary_macOS_arm64")!
    static let binarySHA256 = "28f5f7d0eb8c029679d4faaa483ec85888af17a9a75977ae9170c21d8ce3428b"

    /// The page where the user signs into their existing Epic account. It ends by showing an
    /// authorizationCode to paste back into `highball epic auth <code>`.
    public static let loginURL = URL(string: "https://legendary.gl/epiclogin")!

    public var binary: URL { paths.home.appending(path: "tools/legendary", directoryHint: .notDirectory) }
    var configDir: URL { paths.home.appending(path: "legendary", directoryHint: .isDirectory) }

    /// Downloads and verifies the pinned Legendary binary if missing.
    public func ensureInstalled(progress: DownloadProgress? = nil) async throws -> URL {
        if FileManager.default.fileExists(atPath: binary.path) { return binary }
        let component = EngineManifest.Component(kind: "tool", url: Self.binaryURL, sha256: Self.binarySHA256,
                                                 size: 15_270_304, license: nil, optional: nil,
                                                 acceptance: nil, extract: nil, note: nil, version: "0.21.0")
        let file = try await EngineStore(paths: paths).download(component, name: "legendary", progress: progress)
        try FileManager.default.createDirectory(at: binary.deletingLastPathComponent(), withIntermediateDirectories: true)
        try? FileManager.default.removeItem(at: binary)
        try FileManager.default.copyItem(at: file, to: binary)
        try FileManager.default.setAttributes([.posixPermissions: 0o755], ofItemAtPath: binary.path)
        // Checksum-verified above; quarantine would otherwise block the unsigned PyInstaller binary.
        try? Shell.run("/usr/bin/xattr", ["-c", binary.path])
        return binary
    }

    var environment: [String: String] { ["LEGENDARY_CONFIG_PATH": configDir.path] }

    /// Captures stdout only. Legendary writes its log lines to stderr and JSON to stdout;
    /// merging them (Shell.capture) breaks JSON parsing.
    @discardableResult
    func capture(_ args: [String]) throws -> String { try captureWithLog(args).out }

    /// legendary's output and its log (stderr), where its warnings appear, such as a missing asset.
    func captureWithLog(_ args: [String]) throws -> (out: String, log: String) {
        let p = Process()
        p.executableURL = binary
        p.arguments = args
        p.environment = ProcessInfo.processInfo.environment.merging(environment) { $1 }
        let out = Pipe(), err = Pipe()
        p.standardOutput = out
        p.standardError = err
        try p.run()
        let data = out.fileHandleForReading.readDataToEndOfFile()
        let errData = err.fileHandleForReading.readDataToEndOfFile()
        p.waitUntilExit()
        guard p.terminationStatus == 0 else {
            throw HighballError.processFailed(command: "legendary " + args.joined(separator: " "),
                                              status: p.terminationStatus,
                                              output: String(decoding: errData.suffix(2000), as: UTF8.self))
        }
        return (String(decoding: data, as: UTF8.self), String(decoding: errData, as: UTF8.self))
    }

    /// Runs legendary streaming each output line (installs are long and progress matters).
    /// `control` lets the caller stop it the way Ctrl-C in a terminal does; `extra` adds to its
    /// environment (WINEPREFIX, for a save folder legendary resolves inside an environment).
    @discardableResult
    public func runStreaming(_ args: [String], control: LegendaryControl? = nil, environment extra: [String: String] = [:],
                             onLine: (@Sendable (String) -> Void)? = nil) throws -> Int32 {
        let p = Process()
        p.executableURL = binary
        p.arguments = args
        p.environment = ProcessInfo.processInfo.environment.merging(environment) { $1 }.merging(extra) { $1 }
        let pipe = Pipe()
        p.standardOutput = pipe
        p.standardError = pipe
        try p.run()
        control?.started(p)
        let reader = pipe.fileHandleForReading
        var buffer = Data()
        while true {
            let chunk = reader.availableData
            if chunk.isEmpty { break }
            buffer.append(chunk)
            while let nl = buffer.firstIndex(of: 0x0A) {
                onLine?(String(decoding: buffer[..<nl], as: UTF8.self))
                buffer.removeSubrange(...nl)
            }
        }
        if !buffer.isEmpty { onLine?(String(decoding: buffer, as: UTF8.self)) }
        p.waitUntilExit()
        return p.terminationStatus
    }

    public var isAuthenticated: Bool {
        FileManager.default.fileExists(atPath: configDir.appending(path: "user.json").path)
    }

    public func authenticate(code: String) throws {
        _ = try capture(["auth", "--disable-webview", "--code", code])
    }

    public func logout() throws { _ = try capture(["auth", "--delete"]) }

    public struct Game: Codable, Sendable {
        public let app_name: String
        public let app_title: String
        /// Epic's own catalog art, embedded by legendary in `list --json` metadata.keyImages.
        /// Wide (DieselGameBox) fits the 460:215 game card; tall (DieselGameBoxTall) is the
        /// 2:3 cover for the future unified library. Same type mapping Heroic uses.
        public let artworkWide: URL?
        public let artworkTall: URL?
        /// The catalog item lists a Mac release beside the Windows one (metadata.releaseInfo's
        /// platforms), which the same purchase includes.
        public let listsMac: Bool
        /// The catalog item names a cloud save folder (metadata.customAttributes.CloudSaveFolder):
        /// Epic's cloud keeps its saves when Epic's own launcher syncs them.
        public var cloudSaves = false

        public init(app_name: String, app_title: String, artworkWide: URL? = nil, artworkTall: URL? = nil, listsMac: Bool = false) {
            self.app_name = app_name; self.app_title = app_title
            self.artworkWide = artworkWide; self.artworkTall = artworkTall; self.listsMac = listsMac
        }

        private enum CodingKeys: String, CodingKey { case app_name, app_title, metadata }
        private enum MetadataKeys: String, CodingKey { case keyImages, releaseInfo, customAttributes }
        private struct KeyImage: Codable { let type: String?; let url: String? }
        private struct ReleaseInfo: Codable { let platform: [String]? }
        private struct CustomAttribute: Codable { let value: String? }

        public init(from decoder: Decoder) throws {
            let c = try decoder.container(keyedBy: CodingKeys.self)
            app_name = try c.decode(String.self, forKey: .app_name)
            app_title = try c.decode(String.self, forKey: .app_title)
            var images: [KeyImage] = []
            var releases: [ReleaseInfo] = []
            if let md = try? c.nestedContainer(keyedBy: MetadataKeys.self, forKey: .metadata) {
                images = (try? md.decode([KeyImage].self, forKey: .keyImages)) ?? []
                releases = (try? md.decode([ReleaseInfo].self, forKey: .releaseInfo)) ?? []
                let attributes = (try? md.decode([String: CustomAttribute].self, forKey: .customAttributes)) ?? [:]
                cloudSaves = !(attributes["CloudSaveFolder"]?.value ?? "").isEmpty
            }
            listsMac = releases.contains { $0.platform?.contains("Mac") == true }
            func first(_ types: [String]) -> URL? {
                for t in types {
                    if let u = images.first(where: { $0.type == t })?.url, let url = URL(string: u) { return url }
                }
                return nil
            }
            artworkWide = first(["DieselGameBox", "OfferImageWide"])
            artworkTall = first(["DieselGameBoxTall", "OfferImageTall", "DieselStoreFrontTall"])
        }

        public func encode(to encoder: Encoder) throws {
            // Artwork and platforms are derived from legendary's metadata on every decode; only
            // identity persists.
            var c = encoder.container(keyedBy: CodingKeys.self)
            try c.encode(app_name, forKey: .app_name)
            try c.encode(app_title, forKey: .app_title)
        }
    }

    /// Games the account owns (Windows builds).
    public func ownedGames() throws -> [Game] {
        let out = try capture(["list", "--platform", "Windows", "--json"])
        return try JSONDecoder().decode([Game].self, from: Data(out.utf8))
    }

    public struct InstalledGame: Codable, Sendable {
        public let app_name: String
        public let install_path: String?
        /// legendary's record of the installed size, in bytes.
        public var install_size: Int64? = nil
        /// Where the game keeps the saves legendary syncs, once it has resolved it (EpicSaves).
        public var save_path: String? = nil
        /// "Windows" or "Mac": which build legendary installed (one per game).
        public var platform: String? = nil

        public var isMac: Bool { platform?.lowercased() == "mac" }
    }

    /// Everything legendary has installed, with where. Legendary's install state is global
    /// across bottles; the bottle association lives in the path, so callers must check it
    /// with `isInstalled(path:inDriveC:)` — a game installed in bottle A is NOT installed
    /// in bottle B (the old Set-of-names API showed Play in bottles that had no files).
    public func installedGames() throws -> [InstalledGame] {
        let out = try capture(["list-installed", "--json"])
        return try JSONDecoder().decode([InstalledGame].self, from: Data(out.utf8))
    }

    /// Legendary's own install records (installed.json in its config folder), app name to install
    /// path, read without running it. Empty when legendary has installed nothing; nil when the
    /// file is there but can't be read.
    public func installRecords() -> [String: String]? {
        let file = configDir.appending(path: "installed.json")
        guard FileManager.default.fileExists(atPath: file.path) else { return [:] }
        guard let data = try? Data(contentsOf: file),
              let all = (try? JSONSerialization.jsonObject(with: data)) as? [String: Any] else { return nil }
        return all.mapValues { (($0 as? [String: Any])?["install_path"] as? String) ?? "" }
    }

    /// Whether legendary still records the game as installed; nil when its records can't be
    /// read. An uninstall is done when the record is gone: legendary deletes the files its
    /// manifest names, then removes the folder only if nothing else is left in it (core.py
    /// `uninstall_game`, `delete_filelist`), so a log, a config or a save keeps the folder.
    public func isRecorded(_ appName: String) -> Bool? {
        installRecords().map { $0[appName] != nil }
    }

    /// The files legendary installed for a game, by its installed manifest, as paths relative to
    /// the install folder. Read offline, with no sign-in, from the manifest file legendary keeps
    /// for the installed version (`list-files --manifest`): `list-files <app>` signs in and
    /// downloads one in 0.21.0, since `main()` always sets a platform. Throws when legendary has
    /// no manifest for it.
    public func installedFiles(_ appName: String) throws -> [String] {
        guard let manifest = installedManifest(appName) else {
            throw HighballError.failed("legendary has no manifest for \(appName)")
        }
        struct File: Decodable { let filename: String }
        let out = try capture(Self.listFilesArguments(manifest: manifest))
        return try JSONDecoder().decode([File].self, from: Data(out.utf8)).map(\.filename)
    }
    static func listFilesArguments(manifest: URL) -> [String] { ["list-files", "--manifest", manifest.path, "--json"] }

    /// The manifest file legendary keeps for a game's installed version, nil when there is none.
    func installedManifest(_ appName: String) -> URL? {
        guard let data = try? Data(contentsOf: configDir.appending(path: "installed.json")),
              let all = (try? JSONSerialization.jsonObject(with: data)) as? [String: Any],
              let entry = all[appName] as? [String: Any] else { return nil }
        return Self.manifestNames(appName, entry: entry)
            .map { configDir.appending(path: "manifests/\($0)") }
            .first { FileManager.default.fileExists(atPath: $0.path) }
    }

    /// The names legendary saves an installed version's manifest under (lgndry.py
    /// `_get_manifest_filename`): with its platform, or without it for an older install.
    static func manifestNames(_ appName: String, entry: [String: Any]) -> [String] {
        guard let version = entry["version"] as? String else { return [] }
        let platform = entry["platform"] as? String ?? "Windows"
        return ["\(appName)_\(platform)_\(version)", "\(appName)_\(version)"].map { cleanFilename($0) + ".manifest" }
    }

    /// legendary's clean_filename: the characters a file name cannot hold, dropped.
    static func cleanFilename(_ name: String) -> String { name.filter { !"<>:\"/\\|?*".contains($0) } }

    /// Legendary's install records, app name to path, keeping only the ones whose folder still
    /// exists. Legendary never notices a removed environment or a deleted game folder, and a
    /// record it keeps showed Guardians of the Galaxy as installed after its bottle was gone (#63).
    public static func installMap(_ games: [InstalledGame]) -> [String: String] {
        Dictionary(uniqueKeysWithValues: games.compactMap { g in
            g.install_path.flatMap { FileManager.default.fileExists(atPath: $0) ? (g.app_name, $0) : nil }
        })
    }

    /// True when an install path lies inside the given bottle's drive_c.
    public static func isInstalled(path: String, inDriveC driveC: URL) -> Bool {
        let p = URL(fileURLWithPath: path).standardizedFileURL.path + "/"
        let c = driveC.standardizedFileURL.path + "/"
        return p.hasPrefix(c)
    }

    /// The install command line. Legendary runs without a terminal here, so every prompt must
    /// be answered on the command line: `-y` covers the confirmations, and `--skip-sdl` the
    /// selective-download prompt (optional language packs), which `-y` does not cover and which
    /// otherwise dies with EOFError the moment it reads stdin (Hogwarts Legacy on Epic, #110).
    /// The defaults install the required data only; language packs can be added later.
    static func installArguments(appName: String, basePath: String, platform: String = "Windows") -> [String] {
        ["install", appName, "--platform", platform, "--base-path", basePath, "-y", "--skip-sdl"]
    }

    /// Installs a game's Mac build into the Mac games folder, beside GOG's (GOGStore.macGamesDir).
    /// legendary keeps one install per game, so the Windows one's record must be dropped first
    /// (EpicBuildSwitch), and only once `hasMacBuild` said yes. Should legendary still fall back
    /// to the Windows build (its install_platform_fallback, on by default and with no flag to
    /// turn it off, makes a missing Mac asset a warning and downloads the Windows build into this
    /// folder, outside every environment), it is stopped at that line, before the download, and the install fails.
    @discardableResult
    public func installMac(_ appName: String, control: LegendaryControl? = nil,
                           onLine: (@Sendable (String) -> Void)? = nil) throws -> Int32 {
        let base = GOGStore.macGamesDir
        try FileManager.default.createDirectory(at: base, withIntermediateDirectories: true)
        let control = control ?? LegendaryControl()
        let fellBack = Collector()
        let status = try runStreaming(Self.installArguments(appName: appName, basePath: base.path, platform: "Mac"), control: control) { line in
            if Self.fellBackToWindows(line) { fellBack.append(line); control.stop() }
            onLine?(line)
        }
        guard fellBack.lines.isEmpty else {
            throw HighballError.failed("Epic has no Mac build of this game to download for your account, so Highball stopped the install before Epic's tool downloaded the Windows build in its place.")
        }
        return status
    }

    /// legendary 0.21.0's warning before it installs the Windows build in place of a missing one:
    /// `App has no asset for platform "Mac", falling back to "Windows".`
    static func fellBackToWindows(_ line: String) -> Bool {
        line.contains("has no asset for platform \"Mac\"") && line.contains("falling back")
    }

    /// Whether Epic has a Mac build of the game for this account to download: the check
    /// legendary's install makes before it falls back to Windows (an asset for the platform),
    /// read from `legendary info --platform Mac`. A catalog listing Mac (Game.listsMac) does not
    /// promise one.
    public func hasMacBuild(_ appName: String) throws -> Bool {
        let (out, log) = try captureWithLog(["info", appName, "--json", "--platform", "Mac"])
        return Self.manifest(Data(out.utf8), log: log, platform: "Mac") != nil
    }

    /// The manifest `legendary info --json --platform <platform>` printed, only when it is that
    /// platform's build. With the platform's asset missing, legendary logs "Asset information
    /// for ... is missing", answers offline and prints the installed build's manifest instead (a
    /// Windows one for a Mac question), so the log must hold no such warning and the manifest's
    /// build version must be the one Epic lists for the platform (game.platform_versions, from
    /// the asset list its install checks). Output that cannot be read is no build.
    static func manifest(_ data: Data, log: String, platform: String) -> [String: Any]? {
        guard !log.contains("Asset information for"),
              let start = data.firstIndex(of: UInt8(ascii: "{")),
              let obj = try? JSONSerialization.jsonObject(with: data[start...]) as? [String: Any],
              let manifest = obj["manifest"] as? [String: Any],
              let versions = (obj["game"] as? [String: Any])?["platform_versions"] as? [String: Any],
              let listed = versions[platform] as? String,
              manifest["build_version"] as? String == listed else { return nil }
        return manifest
    }

    /// Installs a game's Windows build into the bottle at drive_c/Games/<folder>.
    @discardableResult
    public func install(_ appName: String, into bottle: Bottle, control: LegendaryControl? = nil,
                        onLine: (@Sendable (String) -> Void)? = nil) throws -> Int32 {
        let base = bottle.driveC.appending(path: "Games", directoryHint: .isDirectory)
        try FileManager.default.createDirectory(at: base, withIntermediateDirectories: true)
        return try runStreaming(Self.installArguments(appName: appName, basePath: base.path), control: control, onLine: onLine)
    }

    /// legendary refuses to start an install while another legendary holds its install lock,
    /// and returns as if it had succeeded, status 0, so the strip said Done over nothing
    /// installed (highball#323, a download from before a restart still running).
    public static func refusedForLock(_ line: String) -> Bool {
        line.contains("Failed to acquire installed data lock")
    }

    /// legendary's reason for refusing an install, as a sentence for the player, from one line of its
    /// output, or nil. Its checks print "[cli] CRITICAL: Not enough available disk space! 51200.00 MiB <
    /// 123456.00 MiB" and exit 1, which reached the player as only "epic install exited with 1, see the
    /// log above" (highball#409, Red Dead Redemption 2, well over 100 GB).
    public static func installFailure(_ line: String) -> String? {
        guard let r = line.range(of: "CRITICAL: ") ?? line.range(of: "ERROR: ") else { return nil }
        let message = line[r.upperBound...].trimmingCharacters(in: .whitespaces)
        guard !message.isEmpty, !message.hasPrefix("Installation cannot proceed") else { return nil }
        if message.hasPrefix("Not enough available disk space") {
            let gb = { (bytes: Int64) in String(format: "%.0f GB", Double(bytes) / 1_073_741_824) }
            if let free = mebibytes(after: "disk space!", in: message), let needed = mebibytes(after: "< ", in: message) {
                return "This Mac doesn't have enough free space for the game. It needs \(gb(needed)) and \(gb(free)) are free. Free some space, then press Install again."
            }
            return "This Mac doesn't have enough free space for the game. Free some space, then press Install again."
        }
        return "Epic's installer stopped with this message. \(message)"
    }

    /// legendary's install log names the download's size before it starts ("Download size:
    /// 95232.19 MiB (Compression savings: 2.1%)") and then, about once a second, how much has
    /// arrived (" - Downloaded: 9075.51 MiB, Written: 9415.55 MiB"). The activity strip shows
    /// them like an engine download's bytes (highball#287). Bytes, or nil for any other line.
    public static func downloadSize(inLegendaryLine line: String) -> Int64? { mebibytes(after: "Download size:", in: line) }
    public static func downloaded(inLegendaryLine line: String) -> Int64? { mebibytes(after: "- Downloaded:", in: line) }

    private static func mebibytes(after label: String, in line: String) -> Int64? {
        guard let r = line.range(of: label) else { return nil }
        let rest = line[r.upperBound...].drop { $0 == " " }
        let number = rest.prefix { $0.isNumber || $0 == "." }
        guard !number.isEmpty, rest.dropFirst(number.count).hasPrefix(" MiB"), let value = Double(number) else { return nil }
        return Int64(value * 1_048_576)
    }

    static func moveArguments(appName: String, basePath: String) -> [String] { ["move", appName, basePath] }

    /// Moves an installed game's folder into another environment's drive_c/Games and rewrites
    /// legendary's record of it, so the game alone plays there (highball#566: the engine switch
    /// moves every game of an environment). Legendary renames the folder, which takes a moment
    /// whatever the game's size, and it refuses another disk. It prints its refusals and still
    /// exits 0, so the files decide: nil when the folder now sits in the new place, else why not.
    public func move(_ appName: String, from installPath: String, into bottle: Bottle,
                     onLine: (@Sendable (String) -> Void)? = nil) throws -> String? {
        let base = bottle.driveC.appending(path: "Games", directoryHint: .isDirectory)
        try FileManager.default.createDirectory(at: base, withIntermediateDirectories: true)
        let refusals = Collector()
        _ = try runStreaming(Self.moveArguments(appName: appName, basePath: base.path)) { line in
            if let r = line.range(of: "ERROR: ") { refusals.append(String(line[r.upperBound...])) }
            onLine?(line)
        }
        let moved = base.appending(path: URL(fileURLWithPath: installPath).lastPathComponent).path
        if FileManager.default.fileExists(atPath: moved), !FileManager.default.fileExists(atPath: installPath) { return nil }
        return refusals.lines.last.map(Self.moveFailure) ?? "Its folder is still at \(installPath)."
    }

    /// Legendary's refusal to move, as a sentence for the player.
    static func moveFailure(_ message: String) -> String {
        if message.hasPrefix("Moving to a different drive is not supported") {
            return "The game is on another disk than that environment, and Epic's tool only moves a game within one disk."
        }
        // 0.21.0 renames straight onto the target: an empty folder there is replaced, a full one
        // fails with errno 66 (measured 2026-10-30). Its own check for that case reads this way.
        if message.contains("Directory not empty") || message.hasPrefix("The target path already contains a folder called") {
            return "That environment already has a folder of that name in drive_c/Games. Remove or rename it, then try again."
        }
        return message
    }

    static func uninstallArguments(appName: String) -> [String] { ["uninstall", appName, "-y"] }
    static func keepFilesUninstallArguments(appName: String) -> [String] { ["uninstall", appName, "-y", "--keep-files", "--skip-uninstaller"] }

    /// Drops legendary's record of an install and keeps its files, so a switch to the other build
    /// can be undone (`restoreSavedRecord`) until the new build is in (EpicBuildSwitch).
    @discardableResult
    public func forgetRecordKeepingFiles(_ appName: String, onLine: (@Sendable (String) -> Void)? = nil) throws -> Int32 {
        try runStreaming(Self.keepFilesUninstallArguments(appName: appName), onLine: onLine)
    }

    /// Removes a game legendary installed. Legendary owns the Epic install state, so it does the
    /// deleting and its library stays right; deleting the folder ourselves would leave it
    /// believing the game is still there (highball#185).
    @discardableResult
    public func uninstall(_ appName: String, onLine: (@Sendable (String) -> Void)? = nil) throws -> Int32 {
        try runStreaming(Self.uninstallArguments(appName: appName), onLine: onLine)
    }

    public struct LaunchInfo: Sendable {
        public let executable: URL
        public let arguments: [String]
        public let workingDirectory: URL
        public let environment: [String: String]
    }

    /// Fresh launch parameters. The auth token inside is single use and expires within minutes,
    /// so call this immediately before each launch and never persist the result.
    public func launchInfo(_ appName: String, offline: Bool = false) throws -> LaunchInfo {
        // --no-wine: we spawn Wine ourselves; without it legendary tries to locate a wine
        // binary on macOS and crashes with IndexError when none is configured.
        var args = ["launch", appName, "--json", "--skip-version-check", "--no-wine"]
        if offline { args.append("--offline") }
        let out = try capture(args)
        guard let start = out.firstIndex(of: "{"),
              let obj = try JSONSerialization.jsonObject(with: Data(out[start...].utf8)) as? [String: Any] else {
            throw HighballError.invalid("unexpected legendary launch output")
        }
        let gameDir = (obj["game_directory"] as? String) ?? ""
        let exe = (obj["game_executable"] as? String) ?? ""
        let workdir = (obj["working_directory"] as? String).flatMap { $0.isEmpty ? nil : $0 } ?? gameDir
        let params = ((obj["egl_parameters"] as? [String]) ?? [])
                   + ((obj["game_parameters"] as? [String]) ?? [])
                   + ((obj["user_parameters"] as? [String]) ?? [])
        let env = (obj["environment"] as? [String: String]) ?? [:]
        guard !gameDir.isEmpty, !exe.isEmpty else {
            throw HighballError.invalid("legendary returned no executable for \(appName)")
        }
        return LaunchInfo(executable: URL(fileURLWithPath: gameDir).appending(path: exe),
                          arguments: params,
                          workingDirectory: URL(fileURLWithPath: workdir),
                          environment: env)
    }
}

/// The last lines a legendary run printed, for the Details of a failure none of them explains
/// (EpicStore.installFailure). The error said "see the log above" and its Details showed only
/// that, never legendary's output (highball-db#961, an install that exited with 1). The download
/// manager's progress block, several lines a second, stays out.
public final class LegendaryTail: @unchecked Sendable {
    private let lock = NSLock()
    private var lines: [String] = []
    private let limit: Int

    public init(limit: Int = 30) { self.limit = limit }

    public func append(_ line: String) {
        guard !line.contains("[DLManager] INFO:"), !line.trimmingCharacters(in: .whitespaces).isEmpty else { return }
        lock.withLock {
            lines.append(line)
            if lines.count > limit { lines.removeFirst(lines.count - limit) }
        }
    }

    public var text: String {
        let lines = lock.withLock { self.lines }
        return lines.isEmpty ? "legendary printed nothing" : "legendary's last lines:\n" + lines.joined(separator: "\n")
    }
}

/// Stops a running legendary the way Ctrl-C in a terminal does. A terminal signals the whole
/// process group, and legendary's downloader runs in child processes, so SIGINT goes to
/// legendary and everything it started. legendary answers by keeping the download's progress,
/// and the same install picks up from there later ("Downloads are resumable, you can interrupt
/// the download with CTRL-C and resume it using the same command later on", its install
/// output). Whatever is still running after the grace period gets SIGTERM, and SIGKILL half a
/// period later, including a child left behind by a parent that already exited. Each process
/// is signalled only while it is the one seen at Stop, by its start time, so a pid taken over
/// in the meantime is never hit. Before this the strip's Stop cancelled a task nothing was
/// listening to, and the download outlived the app (highball#323).
public final class LegendaryControl: @unchecked Sendable {
    private let lock = NSLock()
    private var process: Process?
    private var stopRequested = false
    /// Seconds between SIGINT and SIGTERM, and SIGKILL at one and a half times that.
    private let grace: TimeInterval

    public init(grace: TimeInterval = 10) { self.grace = grace }

    func started(_ process: Process) {
        let stopNow = lock.withLock { () -> Bool in self.process = process; return stopRequested }
        if stopNow { stop() }
    }

    public func stop() {
        let process = lock.withLock { () -> Process? in stopRequested = true; return self.process }
        guard let process else { return }
        let seen = Self.members(of: process)
        Self.signal(seen, SIGINT)
        DispatchQueue.global().asyncAfter(deadline: .now() + grace) { Self.signal(seen + Self.members(of: process), SIGTERM) }
        DispatchQueue.global().asyncAfter(deadline: .now() + grace * 1.5) { Self.signal(seen + Self.members(of: process), SIGKILL) }
    }

    struct Member: Hashable {
        let pid: pid_t
        let started: UInt64
    }

    /// legendary and every process under it, each with its start time, or none once legendary
    /// itself has exited.
    private static func members(of process: Process) -> [Member] {
        guard process.isRunning else { return [] }
        return tree(process.processIdentifier).compactMap { pid in startTime(pid).map { Member(pid: pid, started: $0) } }
    }

    private static func signal(_ members: [Member], _ signal: Int32) {
        for member in Set(members) where startTime(member.pid) == member.started { kill(member.pid, signal) }
    }

    /// When the process started, in microseconds, or nil when there is no such process.
    static func startTime(_ pid: pid_t) -> UInt64? {
        var info = proc_bsdinfo()
        let size = Int32(MemoryLayout<proc_bsdinfo>.size)
        guard proc_pidinfo(pid, PROC_PIDTBSDINFO, 0, &info, size) == size else { return nil }
        return info.pbi_start_tvsec &* 1_000_000 &+ info.pbi_start_tvusec
    }

    /// A process and every process under it, parents first.
    static func tree(_ root: pid_t) -> [pid_t] {
        var pids = [root], next = 0
        while next < pids.count {
            let parent = pids[next]; next += 1
            let count = proc_listchildpids(parent, nil, 0)
            guard count > 0 else { continue }
            var children = [pid_t](repeating: 0, count: Int(count) + 8)
            let found = children.withUnsafeMutableBytes { proc_listchildpids(parent, $0.baseAddress, Int32($0.count)) }
            for child in children.prefix(Int(max(found, 0))) where child > 0 && !pids.contains(child) { pids.append(child) }
        }
        return pids
    }
}